webMethods Integration Server BuiltInServicesReference

Version 9.6

April 2014

This document applies to webMethods Integration Server Version 9.6 and to all subsequent releases.
Specications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright 1998-2014 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or
its aliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA Inc. and/or its subsidiaries and/or its aliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
hp://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products. This document is part of the product documentation, located at
hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
Document ID: IS-BIS-RF-96-20141118

M
Table of Contents

Table of Contents
About this Guide............................................................................................................................21
Document Conventions............................................................................................................ 25
Documentation Installation........................................................................................................25
Online Information.................................................................................................................... 26
ART Folder......................................................................................................................................27
Summary of Elements in this Folder........................................................................................28
pub.art:listRegisteredAdapters...........................................................................................30
pub.art.connection:disableConnection...............................................................................31
pub.art.connection:enableConnection............................................................................... 31
pub.art.connection:getConnectionStatistics.......................................................................32
pub.art.connection:listAdapterConnections....................................................................... 32
pub.art.connection:queryConnectionState.........................................................................33
pub.art.listener:disableListener.......................................................................................... 34
pub.art.listener:enableListener...........................................................................................35
pub.art.listener:listAdapterListeners...................................................................................35
pub.art.listener:queryListenerState.................................................................................... 36
pub.art.listener:resumeListener......................................................................................... 37
pub.art.listener:setListenerNodeConnection......................................................................37
pub.art.listener:suspendListener........................................................................................38
pub.art.notification:disableListenerNotification...................................................................39
pub.art.notification:disablePollingNotification.....................................................................39
pub.art.notification:enableListenerNotification................................................................... 39
pub.art.notification:enablePollingNotification..................................................................... 40
pub.art.notification:listAdapterListenerNotifications........................................................... 40
pub.art.notification:listAdapterPollingNotifications............................................................. 41
pub.art.notification:queryListenerNotificationState.............................................................42
pub.art.notification:queryPollingNotificationState...............................................................43
pub.art.notification:resumePollingNotification.................................................................... 44
pub.art.notification:setListenerNotificationNodeListener....................................................44
pub.art.notification:setPollingNotificationNodeConnection.................................................45
pub.art.notification:suspendPollingNotification.................................................................. 46
pub.art.service:listAdapterServices....................................................................................46
pub.art.service:setAdapterServiceNodeConnection.......................................................... 47
pub.art.transaction:commitTransaction.............................................................................. 47
pub.art.transaction:rollbackTransaction............................................................................. 48
pub.art.transaction:setTransactionTimeout........................................................................49
pub.art.transaction:startTransaction...................................................................................50
Cache Folder.................................................................................................................................. 53
About Checkpoint Restart.........................................................................................................54

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

Summary of Elements in this Folder........................................................................................55

pub.cache:containsKey......................................................................................................58
pub.cache:get.................................................................................................................... 58
pub.cache:getKeys............................................................................................................ 60
pub.cache:put.................................................................................................................... 61
pub.cache:remove............................................................................................................. 62
pub.cache:search...............................................................................................................63
pub.cache.admin:clearAllCaches.......................................................................................66
pub.cache.admin:clearCache............................................................................................ 67
pub.cache.admin:disableCache.........................................................................................68
pub.cache.admin:enableCache......................................................................................... 69
pub.cache.admin:evictExpiredElements............................................................................ 69
pub.cache.admin:isCacheDisabled....................................................................................70
pub.cache.atomic:putIfAbsent............................................................................................71
pub.cache.atomic:remove..................................................................................................72
pub.cache.atomic:replace.................................................................................................. 73
pub.cache.atomic:replaceIfKeyExists................................................................................ 74
pub.cache.bulk:isClusterBulkLoadEnabled........................................................................75
pub.cache.bulk:isNodeBulkLoadEnabled.......................................................................... 76
pub.cache.bulk:setNodeBulkLoadEnabled........................................................................ 77
pub.cache.bulk:waitUntilClusterBulkLoadComplete...........................................................78
pub.cache.lock:acquireLock...............................................................................................78
pub.cache.lock:isLockedByCurrentThread........................................................................ 80
pub.cache.lock:releaseLock...............................................................................................81
Client Folder................................................................................................................................... 83
Summary of Elements in this Folder........................................................................................84
pub.client:ftp.......................................................................................................................88
pub.client.ftp:append..........................................................................................................92
pub.client.ftp:cd..................................................................................................................92
pub.client.ftp:cdls............................................................................................................... 93
pub.client.ftp:delete............................................................................................................94
pub.client.ftp:dir..................................................................................................................94
pub.client.ftp:get.................................................................................................................95
pub.client.ftp:getCompletedNotification............................................................................. 97
pub.client.ftp:login.............................................................................................................. 98
pub.client.ftp:logout..........................................................................................................101
pub.client.ftp:ls................................................................................................................. 102
pub.client.ftp:mdelete.......................................................................................................103
pub.client.ftp:mget............................................................................................................104
pub.client.ftp:mput............................................................................................................104
pub.client.ftp:put...............................................................................................................105
pub.client.ftp:putCompletedNotification........................................................................... 107
pub.client.ftp:quote...........................................................................................................108
pub.client.ftp:rename....................................................................................................... 108

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

pub.client.ftp:sessioninfo..................................................................................................109
pub.client:http...................................................................................................................110
pub.client.ldap:add...........................................................................................................119
pub.client.ldap:bind.......................................................................................................... 120
pub.client.ldap:cancelNotification.....................................................................................121
pub.client.ldap:compare...................................................................................................122
pub.client.ldap:delete....................................................................................................... 123
pub.client.ldap:modify...................................................................................................... 125
pub.client.ldap:registerNotification................................................................................... 126
pub.client.ldap:rename.....................................................................................................128
pub.client.ldap:search...................................................................................................... 129
pub.client.oauth:executeRequest.....................................................................................131
pub.client.sftp:cd.............................................................................................................. 135
pub.client.sftp:chgrp.........................................................................................................136
pub.client.sftp:chmod....................................................................................................... 136
pub.client.sftp:chown....................................................................................................... 137
pub.client.sftp:get.............................................................................................................137
pub.client.sftp:login.......................................................................................................... 139
pub.client.sftp:logout........................................................................................................ 139
pub.client.sftp:ls............................................................................................................... 140
pub.client.sftp:mkdir......................................................................................................... 141
pub.client.sftp:put.............................................................................................................141
pub.client.sftp:pwd........................................................................................................... 142
pub.client.sftp:rename......................................................................................................143
pub.client.sftp:rm..............................................................................................................144
pub.client.sftp:rmdir..........................................................................................................144
pub.client.sftp:symlink......................................................................................................145
pub.client:smtp.................................................................................................................145
pub.client:soapClient........................................................................................................149
pub.client:soapHTTP....................................................................................................... 166
pub.client:soapRPC......................................................................................................... 170
Date Folder................................................................................................................................... 175
Pattern String Symbols...........................................................................................................176
Time Zones.............................................................................................................................177
Examples................................................................................................................................ 179
Notes on Invalid Dates........................................................................................................... 180
Summary of Elements in this Folder......................................................................................180
pub.date:calculateDateDifference....................................................................................181
pub.date:currentNanoTime.............................................................................................. 182
pub.date:dateBuild........................................................................................................... 182
pub.date:dateTimeBuild................................................................................................... 183
pub.date:dateTimeFormat................................................................................................185
pub.date:elapsedNanoTime............................................................................................. 186
pub.date:formatDate........................................................................................................ 187

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

pub.date:getCurrentDate................................................................................................. 188
pub.date:getCurrentDateString........................................................................................ 188
pub.date:getWorkingDays................................................................................................189
Db Folder...................................................................................................................................... 191
Summary of Elements in this Folder......................................................................................192
pub.db:call........................................................................................................................194
pub.db:clearTransaction...................................................................................................196
pub.db:close.....................................................................................................................197
pub.db:closeAll.................................................................................................................198
pub.db:commit................................................................................................................. 198
pub.db:connect................................................................................................................ 199
pub.db:delete................................................................................................................... 201
pub.db:execSQL.............................................................................................................. 203
pub.db:getProcInfo...........................................................................................................207
pub.db:getProcs...............................................................................................................208
pub.db:getTableInfo......................................................................................................... 210
pub.db:getTables..............................................................................................................211
pub.db:insert.................................................................................................................... 213
pub.db:query.................................................................................................................... 215
pub.db:rollback.................................................................................................................216
pub.db:startTransaction................................................................................................... 217
pub.db:update.................................................................................................................. 218
Document Folder......................................................................................................................... 221
Summary of Elements in this Folder......................................................................................222
pub.document:bytesToDocument.................................................................................... 223
pub.document:deleteDocuments..................................................................................... 224
pub.document:documentListToDocument........................................................................224
pub.document:documentToBytes.....................................................................................226
pub.document:documentToDocumentList........................................................................228
pub.document:documentToXMLValues............................................................................230
pub.document:groupDocuments......................................................................................230
pub.document:insertDocument........................................................................................ 231
pub.document:searchDocuments.................................................................................... 232
pub.document:sortDocuments......................................................................................... 233
pub.document:XMLValuesToDocument........................................................................... 234
Event Folder................................................................................................................................. 237
Summary of Elements in this Folder......................................................................................238
pub.event:addSubscriber................................................................................................. 242
pub.event:alarm............................................................................................................... 245
pub.event:alarmInfo......................................................................................................... 246
pub.event:audit................................................................................................................ 247
pub.event:auditError........................................................................................................ 248
pub.event:auditErrorInfo.................................................................................................. 250

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

pub.event:auditInfo.......................................................................................................... 251
pub.event:callstackItem................................................................................................... 252
pub.event:deleteSubscriber............................................................................................. 252
pub.event.eda:event........................................................................................................ 254
pub.event.eda:eventToDocument.................................................................................... 255
pub.event.eda:schema_event..........................................................................................257
pub.event.eda:send......................................................................................................... 257
pub.event:error.................................................................................................................263
pub.event:errorInfo...........................................................................................................263
pub.event:exception.........................................................................................................264
pub.event:exceptionInfo...................................................................................................266
pub.event:gdEnd..............................................................................................................267
pub.event:gdEndInfo........................................................................................................268
pub.event:gdStart.............................................................................................................268
pub.event:gdStartInfo.......................................................................................................269
pub.event:getEventTypes................................................................................................ 270
pub.event:getSubscribers................................................................................................ 270
pub.event:jmsReceiveErrorEvent.................................................................................... 272
pub.event:jmsSendErrorEvent......................................................................................... 274
pub.event:journal............................................................................................................. 275
pub.event:journalInfo....................................................................................................... 276
pub.event:modifySubscriber............................................................................................ 278
pub.event.nerv:eventToDocument................................................................................... 282
pub.event.nerv:send........................................................................................................ 283
pub.event:portStatus........................................................................................................286
pub.event:portStatusInfo..................................................................................................286
pub.event:reloadEventManagerSettings..........................................................................287
pub.event:replication........................................................................................................287
pub.event:replicationInfo..................................................................................................288
pub.event:saveEventManagerSettings............................................................................ 289
pub.event:security............................................................................................................289
pub.event:securityInfo......................................................................................................291
pub.event:sessionEnd......................................................................................................292
pub.event:sessionEndInfo................................................................................................293
pub.event:sessionExpire..................................................................................................294
pub.event:sessionExpireInfo............................................................................................294
pub.event:sessionStart.................................................................................................... 295
pub.event:sessionStartInfo.............................................................................................. 296
pub.event:stat.................................................................................................................. 296
pub.event:statInfo............................................................................................................ 298
pub.event:txEnd............................................................................................................... 300
pub.event:txEndInfo......................................................................................................... 300
pub.event:txStart..............................................................................................................301
pub.event:txStartInfo........................................................................................................302

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

File Folder.....................................................................................................................................303
File Access Control Configuration for the pub.file Services................................................... 304
Parameter Settings................................................................................................................. 304
Summary of Elements in this Folder......................................................................................305
pub.file:bytesToFile.......................................................................................................... 306
pub.file:checkFileExistence..............................................................................................307
pub.file:copyFile............................................................................................................... 307
pub.file:deleteFile.............................................................................................................308
pub.file:getFile..................................................................................................................309
pub.file:listFiles................................................................................................................ 310
pub.file:moveFile..............................................................................................................311
pub.file:readerToFile........................................................................................................ 312
pub.file:streamToFile........................................................................................................313
pub.file:stringToFile.......................................................................................................... 314
Flat File Folder............................................................................................................................. 317
Summary of Elements in the Flat File Folder........................................................................ 318
pub.flatFile:convertToString............................................................................................. 320
pub.flatFile:convertToValues............................................................................................ 325
pub.flatFile:FormatService............................................................................................... 331
pub.flatFile:getSupportedEncodings................................................................................ 334
pub.flatFile.generate:createDocumentType..................................................................... 335
pub.flatFile.generate:createFFDictionary.........................................................................335
pub.flatFile.generate:deleteFFDictionary......................................................................... 336
pub.flatFile.generate:deleteFFDictionaryEntry.................................................................337
pub.flatFile.generate:deleteFFSchema............................................................................338
pub.flatFile.generate:FFDictionary...................................................................................338
pub.flatFile.generate:FFSchema......................................................................................341
pub.flatFile.generate:findDependants.............................................................................. 344
pub.flatFile.generate:findReferences............................................................................... 344
pub.flatFile.generate:getFFDictionaryAsXML.................................................................. 345
pub.flatFile.generate:getFFDictionaryEntryAsXML..........................................................346
pub.flatFile.generate:getFFSchemaAsXML..................................................................... 346
pub.flatFile.generate:listFFDictionaryEntries................................................................... 347
pub.flatFile.generate:saveXMLAsFFDictionary................................................................348
pub.flatFile.generate:saveXMLAsFFSchema...................................................................349
pub.flatFile.generate:updateFFDictionaryEntryFromXML................................................351
Flow Folder...................................................................................................................................353
Summary of Elements in this Folder......................................................................................354
pub.flow:clearPipeline...................................................................................................... 356
pub.flow:debugLog...........................................................................................................356
pub.flow:getLastError.......................................................................................................357
pub.flow:getRetryCount................................................................................................... 358
pub.flow:getSession.........................................................................................................359

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

pub.flow:getTransportInfo................................................................................................ 359
pub.flow:invokeService.................................................................................................... 360
pub.flow:restorePipeline...................................................................................................361
pub.flow:restorePipelineFromFile.....................................................................................362
pub.flow:savePipeline...................................................................................................... 363
pub.flow:savePipelineToFile.............................................................................................364
pub.flow:setCustomContextID......................................................................................... 365
pub.flow:setResponse......................................................................................................366
pub.flow:setResponse2....................................................................................................368
pub.flow:setResponseCode............................................................................................. 370
pub.flow:setResponseHeader..........................................................................................370
pub.flow:setResponseHeaders........................................................................................ 373
pub.flow:throwExceptionForRetry.................................................................................... 374
pub.flow:tracePipeline......................................................................................................375
pub.flow:transportInfo...................................................................................................... 375
Hashtable Folder..........................................................................................................................383
Summary of Elements in this Folder......................................................................................384
pub.hashtable:containsKey..............................................................................................384
pub.hashtable:createHashtable....................................................................................... 385
pub.hashtable:get............................................................................................................ 385
pub.hashtable:listKeys..................................................................................................... 385
pub.hashtable:put............................................................................................................ 386
pub.hashtable:remove..................................................................................................... 386
pub.hashtable:size........................................................................................................... 387
IO Folder....................................................................................................................................... 389
Summary of Elements in this Folder......................................................................................390
pub.io:bytesToStream...................................................................................................... 391
pub.io:close......................................................................................................................392
pub.io:createByteArray.................................................................................................... 392
pub.io:mark...................................................................................................................... 393
pub.io:markSupported......................................................................................................394
pub.io:read....................................................................................................................... 395
pub.io:readAsString......................................................................................................... 395
pub.io:readerToString.......................................................................................................396
pub.io:reset...................................................................................................................... 397
pub.io:skip........................................................................................................................397
pub.io:streamToBytes...................................................................................................... 398
pub.io:streamToReader....................................................................................................399
pub.io:streamToString...................................................................................................... 399
pub.io:stringToReader......................................................................................................400
pub.io:stringToStream...................................................................................................... 400
JDBC Folder................................................................................................................................. 401
Summary of Elements in this Folder......................................................................................402

webMethods Integration Server Built-In Services Reference Version 9.6

M
Table of Contents

pub.jdbc:getPoolInfo........................................................................................................ 402
JMS Folder....................................................................................................................................405
Summary of Elements in This Folder.....................................................................................406
pub.jms:acknowledge...................................................................................................... 407
pub.jms:batchTriggerSpec............................................................................................... 408
pub.jms:createConsumer.................................................................................................408
pub.jms:documentResolverSpec..................................................................................... 412
pub.jms:JMSMessage......................................................................................................413
pub.jms:receive................................................................................................................416
pub.jms:reply....................................................................................................................421
pub.jms:send....................................................................................................................429
pub.jms:sendAndWait...................................................................................................... 439
pub.jms:sendBatch.......................................................................................................... 458
pub.jms:triggerSpec......................................................................................................... 467
pub.jms:waitForReply...................................................................................................... 467
pub.jms.wmjms:receiveStream........................................................................................ 472
pub.jms.wmjms:sendStream............................................................................................474
JSON Folder................................................................................................................................. 477
Data Type Mapping................................................................................................................ 478
Summary of Elements in This Folder.....................................................................................479
pub.json:documentToJSONString....................................................................................479
pub.json:jsonStreamToDocument.................................................................................... 480
pub.json:jsonStringToDocument...................................................................................... 481
List Folder.....................................................................................................................................483
Summary of Elements in this Folder......................................................................................484
pub.list:addItemToVector..................................................................................................484
pub.list:appendToDocumentList.......................................................................................485
pub.list:appendToStringList..............................................................................................486
pub.list:sizeOfList.............................................................................................................487
pub.list:stringListToDocumentList.................................................................................... 487
pub.list:vectorToArray...................................................................................................... 488
Math Folder...................................................................................................................................491
Summary of Elements in this Folder......................................................................................492
pub.math:absoluteValue...................................................................................................494
pub.math:addFloatList..................................................................................................... 494
pub.math:addFloats......................................................................................................... 495
pub.math:addIntList......................................................................................................... 496
pub.math:addInts............................................................................................................. 497
pub.math:addObjects.......................................................................................................497
pub.math:divideFloats......................................................................................................498
pub.math:divideInts..........................................................................................................499
pub.math:divideObjects................................................................................................... 500

webMethods Integration Server Built-In Services Reference Version 9.6

10

M
Table of Contents

pub.math:max.................................................................................................................. 500
pub.math:min................................................................................................................... 501
pub.math:multiplyFloatList............................................................................................... 501
pub.math:multiplyFloats................................................................................................... 502
pub.math:multiplyIntList................................................................................................... 503
pub.math:multiplyInts....................................................................................................... 504
pub.math:multiplyObjects.................................................................................................505
pub.math:randomDouble................................................................................................. 505
pub.math:roundNumber................................................................................................... 506
pub.math:subtractFloats.................................................................................................. 506
pub.math:subtractInts...................................................................................................... 508
pub.math:subtractObjects................................................................................................ 508
pub.math:toNumber......................................................................................................... 509
Metadata Folder........................................................................................................................... 511
Summary of Elements in this Folder......................................................................................512
pub.metadata.assets:publishPackages........................................................................... 512
MIME Folder..................................................................................................................................515
Summary of Elements in this Folder......................................................................................516
pub.mime:addBodyPart................................................................................................... 517
pub.mime:addMimeHeader..............................................................................................521
pub.mime:createMimeData..............................................................................................523
pub.mime:getBodyPartContent........................................................................................526
pub.mime:getBodyPartHeader.........................................................................................527
pub.mime:getContentType...............................................................................................529
pub.mime:getEnvelopeStream.........................................................................................529
pub.mime:getMimeHeader...............................................................................................531
pub.mime:getNumParts................................................................................................... 532
pub.mime:getPrimaryContentType.................................................................................. 533
pub.mime:getSubContentType........................................................................................ 534
pub.mime:mergeHeaderAndBody....................................................................................535
OAuth Folder................................................................................................................................ 537
Summary of Elements in this Folder......................................................................................538
pub.oauth:authorize......................................................................................................... 538
pub.oauth:getAccessToken..............................................................................................540
pub.oauth:refreshAccessToken........................................................................................542
Packages Folder.......................................................................................................................... 545
Summary of Elements in this Folder......................................................................................546
pub.packages:activatePackage....................................................................................... 546
pub.packages:backupPackage........................................................................................ 547
pub.packages:disablePackage........................................................................................ 548
pub.packages:enablePackage.........................................................................................549
pub.packages:installPackage.......................................................................................... 549

webMethods Integration Server Built-In Services Reference Version 9.6

11

M
Table of Contents

pub.packages:recoverPackage........................................................................................551
pub.packages:reloadPackage..........................................................................................552
PKI Folder..................................................................................................................................... 553
Summary of Elements in this Folder......................................................................................554
pub.pki.pkcs7:sign........................................................................................................... 554
pub.pki.pkcs7:verify......................................................................................................... 556
pub.pki.smime.createSignedAndEncryptedData..............................................................557
pub.pki.smime.createSignedData.................................................................................... 559
pub.pki.smime:processEncryptedData............................................................................ 559
pub.pki.smime:processSignedData................................................................................. 561
Publish Folder.............................................................................................................................. 565
Summary of Elements in this Folder......................................................................................566
pub.publish:deliver........................................................................................................... 567
pub.publish:deliverAndWait..............................................................................................568
pub.publish:documentResolverSpec............................................................................... 571
pub.publish:envelope....................................................................................................... 573
pub.publish:getRedeliveryCount...................................................................................... 578
pub.publish:publish.......................................................................................................... 580
pub.publish:publishAndWait.............................................................................................582
pub.publish:reply..............................................................................................................586
pub.publish:syncToBroker................................................................................................588
pub.publish:waitForReply.................................................................................................589
pub.publish.notification:error............................................................................................591
Remote Folder..............................................................................................................................593
Summary of Elements in this Folder......................................................................................594
pub.remote:invoke........................................................................................................... 595
pub.remote.gd:end...........................................................................................................597
pub.remote.gd:getStatus..................................................................................................597
pub.remote.gd:invoke...................................................................................................... 598
pub.remote.gd:restart.......................................................................................................599
pub.remote.gd:retrieve.....................................................................................................599
pub.remote.gd:send......................................................................................................... 600
pub.remote.gd:start..........................................................................................................600
pub.remote.gd:submit...................................................................................................... 601
Replicator Folder......................................................................................................................... 603
Summary of Elements in this Folder......................................................................................604
pub.replicator:addReleaseRegistryEntry..........................................................................605
pub.replicator:deleteReleaseRegistryEntry......................................................................606
pub.replicator:distributeViaFTP........................................................................................607
pub.replicator:distributeViaSvcPull...................................................................................608
pub.replicator:distributeViaSvcPush................................................................................ 609
pub.replicator:generateReplicationEvent......................................................................... 609

webMethods Integration Server Built-In Services Reference Version 9.6

12

M
Table of Contents

pub.replicator:getLocalReleasedList................................................................................609
pub.replicator:getRemoteReleasedList............................................................................610
pub.replicator:notifyPackageRelease.............................................................................. 611
pub.replicator:packageCreation....................................................................................... 612
Report Folder............................................................................................................................... 615
Summary of Elements in this Folder......................................................................................616
pub.report:runFileTemplate.............................................................................................. 616
pub.report:runFileTemplateOnPipe.................................................................................. 617
pub.report:runStringTemplate.......................................................................................... 617
pub.report:runStringTemplateOnPipe.............................................................................. 618
pub.report:runTemplate....................................................................................................618
pub.report:runTemplateOnPipe........................................................................................619
Scheduler Folder..........................................................................................................................621
Summary of Elements in this Folder......................................................................................622
pub.scheduler:addComplexTask......................................................................................623
pub.scheduler:addOneTimeTask..................................................................................... 626
pub.scheduler:addRepeatingTask....................................................................................628
pub.scheduler:cancelTask................................................................................................631
pub.scheduler:getTaskIDs................................................................................................631
pub.scheduler:getTaskInfo............................................................................................... 632
pub.scheduler:getUserTaskList........................................................................................636
pub.scheduler:migrateTasksToJDBC............................................................................... 636
pub.scheduler:resumeTask.............................................................................................. 637
pub.scheduler:suspendTask............................................................................................ 638
pub.scheduler:updateComplexTask.................................................................................639
pub.scheduler:updateOneTimeTask................................................................................ 642
pub.scheduler:updateRepeatingTask...............................................................................644
Schema Folder............................................................................................................................. 649
Summary of Elements in this Folder......................................................................................650
pub.schema:createXSD................................................................................................... 651
pub.schema:validate........................................................................................................ 653
pub.schema:validatePipeline........................................................................................... 656
pub.schema.w3c.............................................................................................................. 657
pub.schema.w3c:datatypes............................................................................................. 657
pub.schema.w3c:structures............................................................................................. 657
pub.schema.w3c:xml....................................................................................................... 657
pub.schema.w3c:xsi.........................................................................................................657
Security Folder.............................................................................................................................659
About the Security Elements..................................................................................................660
Summary of Elements in this Folder......................................................................................661
pub.security:clearKeyAndChain.......................................................................................663
pub.security:setKeyAndChain..........................................................................................664

webMethods Integration Server Built-In Services Reference Version 9.6

13

M
Table of Contents

pub.security:setKeyAndChainFromBytes.........................................................................665
pub.security.enterpriseGateway:alertSpec.......................................................................666
pub.security.keystore:getCertificate................................................................................. 668
pub.security.keystore:getKeyAndChain........................................................................... 669
pub.security.keystore:getTrustedCertificates................................................................... 669
pub.security.keystore:setKeyAndChain............................................................................670
pub.security.keystore.pkcs7:sign..................................................................................... 670
pub.security.outboundPasswords:setPassword...............................................................671
pub.security.outboundPasswords:getPassword...............................................................673
pub.security.outboundPasswords:listKeys....................................................................... 674
pub.security.outboundPasswords:removePassword........................................................674
pub.security.outboundPasswords:updatePassword.........................................................675
pub.security.pkcs7:sign....................................................................................................675
pub.security.pkcs7:verify..................................................................................................677
pub.security.util:createMessageDigest.............................................................................678
pub.security.util:getCertificateInfo.................................................................................... 679
pub.security.util:loadPKCS7CertChain.............................................................................680
pub.security.util:createSecureString.................................................................................680
pub.security.util:convertSecureString...............................................................................681
pub.security.util:destroySecureString...............................................................................682
pub.security.xml:decryptXML........................................................................................... 682
pub.security.xml:encryptXML........................................................................................... 684
pub.security.xml:signXML................................................................................................ 686
pub.security.xml:verifyXML.............................................................................................. 692
SMIME Folder............................................................................................................................... 695
Summary of Elements in this Folder......................................................................................696
pub.smime:createCertsOnlyData.....................................................................................697
pub.smime:createEncryptedData.....................................................................................697
pub.smime:createSignedAndEncryptedData................................................................... 698
pub.smime:createSignedData..........................................................................................700
pub.smime:processCertsOnlyData.................................................................................. 702
pub.smime:processEncryptedData.................................................................................. 702
pub.smime:processSignedData....................................................................................... 703
pub.smime.keystore:createSignedAndEncryptedData.....................................................706
pub.smime.keystore:createSignedData........................................................................... 708
pub.smime.keystore:processEncryptedData....................................................................708
SOAP Folder.................................................................................................................................711
Summary of Elements in this Folder......................................................................................712
pub.soap.handler:addBodyBlock..................................................................................... 721
pub.soap.handler:addFaultBlock..................................................................................... 724
pub.soap.handler:addHeaderBlock..................................................................................726
pub.soap.handler:addHeaderElement............................................................................. 730
pub.soap.handler:generateDocumentTypesFromWSDL................................................. 733
pub.soap.handler:getBodyBlock...................................................................................... 735
webMethods Integration Server Built-In Services Reference Version 9.6

14

M
Table of Contents

pub.soap.handler:getBodyBlockQNames........................................................................ 737
pub.soap.handler:getFaultBlock...................................................................................... 738
pub.soap.handler:getHeaderBlock...................................................................................740
pub.soap.handler:getHeaderBlockQNames.................................................................... 742
pub.soap.handler:getHeaderElement.............................................................................. 743
pub.soap.handler:getInitialSOAPRequest....................................................................... 746
pub.soap.handler:getMessageAddressingProperties...................................................... 747
pub.soap.handler:getProperty..........................................................................................749
pub.soap.handler:getServicePipeline.............................................................................. 750
pub.soap.handler:getSOAPMessage...............................................................................752
pub.soap.handler:getWebServiceInvocationProperties................................................... 753
pub.soap.handler:handlerSpec........................................................................................ 755
pub.soap.handler:hasFaultMessage................................................................................756
pub.soap.handler:listConsumer....................................................................................... 757
pub.soap.handler:listProvider.......................................................................................... 758
pub.soap.handler:registerConsumer................................................................................759
pub.soap.handler:registerProvider...................................................................................760
pub.soap.handler:registerWmConsumer......................................................................... 760
pub.soap.handler:registerWmProvider.............................................................................762
pub.soap.handler:removeBodyBlock............................................................................... 763
pub.soap.handler:removeHeaderBlock............................................................................764
pub.soap.handler:removeHeaderElement....................................................................... 766
pub.soap.handler:removeProperty...................................................................................767
pub.soap.handler:setProperty..........................................................................................768
pub.soap.handler:setSOAPMessage...............................................................................769
pub.soap.handler:unregisterConsumer............................................................................769
pub.soap.handler:unregisterProvider...............................................................................770
pub.soap.handler:updateFaultBlock................................................................................ 770
pub.soap.processor:list.................................................................................................... 772
pub.soap.processor:processMessage............................................................................. 774
pub.soap.processor:processRPCMessage......................................................................774
pub.soap.processor:registerProcessor............................................................................ 775
pub.soap.processor:unregisterProcessor........................................................................ 776
pub.soap.schema:encoding............................................................................................. 777
pub.soap.schema:encoding_1_2..................................................................................... 777
pub.soap.schema:envelope............................................................................................. 777
pub.soap.schema:envelope_1_2..................................................................................... 777
pub.soap.utils:addBodyEntry........................................................................................... 777
pub.soap.utils:addHeaderEntry........................................................................................779
pub.soap.utils:addTrailer..................................................................................................781
pub.soap.utils:callbackServiceSpec.................................................................................782
pub.soap.utils:convertToVersionSpecificSOAPFault........................................................782
pub.soap.utils:createSoapData........................................................................................787
pub.soap.utils:createXOPObject......................................................................................788
pub.soap.utils:exitUnableToUnderstand.......................................................................... 789

webMethods Integration Server Built-In Services Reference Version 9.6

15

M
Table of Contents

pub.soap.utils:getActor.................................................................................................... 790
pub.soap.utils:getBody.....................................................................................................791
pub.soap.utils:getBodyEntries......................................................................................... 791
pub.soap.utils:getDocument............................................................................................ 792
pub.soap.utils:getEncoding..............................................................................................793
pub.soap.utils:getHeader................................................................................................. 793
pub.soap.utils:getHeaderEntries......................................................................................794
pub.soap.utils:getMustUnderstand.................................................................................. 795
pub.soap.utils:getQName................................................................................................ 796
pub.soap.utils:getTrailers................................................................................................. 797
pub.soap.utils:getXOPObjectContent.............................................................................. 798
pub.soap.utils:QName..................................................................................................... 799
pub.soap.utils:removeBodyEntry..................................................................................... 800
pub.soap.utils:removeHeaderEntry..................................................................................801
pub.soap.utils:removeTrailer............................................................................................802
pub.soap.utils:requestResponseSpec............................................................................. 803
pub.soap.utils:resetWSDEffectivePolicy.......................................................................... 803
pub.soap.utils.setWSDEffectivePolicy............................................................................. 804
pub.soap.utils:soapDataToBytes......................................................................................805
pub.soap.utils:soapDataToString..................................................................................... 805
pub.soap.utils:soapFault.................................................................................................. 806
pub.soap.utils:streamToSoapData................................................................................... 807
pub.soap.utils:stringToSoapData..................................................................................... 808
pub.soap.utils:validateSoapData..................................................................................... 809
pub.soap.wsa:action........................................................................................................ 810
pub.soap.wsa:faultTo....................................................................................................... 810
pub.soap.wsa:from...........................................................................................................812
pub.soap.wsa:messageID................................................................................................813
pub.soap.wsa:problemAction...........................................................................................813
pub.soap.wsa:problemHeaderQName.............................................................................814
pub.soap.wsa:problemIRI................................................................................................ 814
pub.soap.wsa:relatesTo................................................................................................... 815
pub.soap.wsa:replyTo...................................................................................................... 816
pub.soap.wsa:retryAfter................................................................................................... 817
pub.soap.wsa:to...............................................................................................................817
pub.soap.wsa:schema_wsa.............................................................................................818
pub.soap.wsa.submission:action..................................................................................... 818
pub.soap.wsa.submission:faultTo.................................................................................... 819
pub.soap.wsa.submission:from........................................................................................821
pub.soap.wsa.submission:messageID.............................................................................822
pub.soap.wsa.submission:relatesTo................................................................................ 823
pub.soap.wsa.submission:replyTo................................................................................... 824
pub.soap.wsa.submission:retryAfter................................................................................ 826
pub.soap.wsa.submission:to............................................................................................826
pub.soap.wsa.submission:schema_wsa_submission......................................................827

webMethods Integration Server Built-In Services Reference Version 9.6

16

M
Table of Contents

pub.soap.wsrm:closeSequence....................................................................................... 827
pub.soap.wsrm:createSequence..................................................................................... 828
pub.soap.wsrm:sendAcknowledgementRequest............................................................. 833
pub.soap.wsrm:terminateSequence................................................................................ 834
pub.soap.wsrm:waitUntilSequenceCompleted.................................................................836
Storage Folder..............................................................................................................................839
About the Storage Elements.................................................................................................. 840
Locking Considerations.......................................................................................................... 841
Entry Locking...................................................................................................................841
Data Store Locking..........................................................................................................841
Automatic Promotion to Exclusive Lock..........................................................................842
Wait Time and Duration.................................................................................................. 842
Sample Flow Service for Checkpoint Restart.........................................................................843
Summary of Elements in this Folder......................................................................................844
pub.storage:add............................................................................................................... 845
pub.storage:closeStore.................................................................................................... 846
pub.storage:deleteStore...................................................................................................846
pub.storage:get................................................................................................................ 847
pub.storage:keys..............................................................................................................848
pub.storage:listLocks....................................................................................................... 849
pub.storage:lock...............................................................................................................850
pub.storage:put................................................................................................................ 852
pub.storage:registerStore................................................................................................ 853
pub.storage:releaseLocks................................................................................................853
pub.storage:remove......................................................................................................... 854
pub.storage:shutdown......................................................................................................855
pub.storage:startup.......................................................................................................... 855
pub.storage:unlock...........................................................................................................855
String Folder.................................................................................................................................857
Summary of Elements in this Folder......................................................................................858
pub.string:base64Decode................................................................................................ 860
pub.string:base64Encode................................................................................................ 860
pub.string:bytesToString.................................................................................................. 861
pub.string:concat..............................................................................................................861
pub.string:HTMLDecode.................................................................................................. 862
pub.string:HTMLEncode.................................................................................................. 862
pub.string:indexOf............................................................................................................863
pub.string:length.............................................................................................................. 864
pub.string:lookupDictionary..............................................................................................864
pub.string:lookupTable..................................................................................................... 865
pub.string:makeString...................................................................................................... 866
pub.string:messageFormat.............................................................................................. 866
pub.string:numericFormat................................................................................................ 867
pub.string:objectToString................................................................................................. 868
webMethods Integration Server Built-In Services Reference Version 9.6

17

M
Table of Contents

pub.string:padLeft............................................................................................................ 869
pub.string:padRight..........................................................................................................870
pub.string:replace............................................................................................................ 871
pub.string:stringToBytes...................................................................................................871
pub.string:substring..........................................................................................................872
pub.string:tokenize...........................................................................................................872
pub.string:toLower........................................................................................................... 873
pub.string:toUpper........................................................................................................... 873
pub.string:trim.................................................................................................................. 874
pub.string:URLDecode.....................................................................................................874
pub.string:URLEncode.....................................................................................................875
Sync Folder.................................................................................................................................. 877
Summary of Elements in this Folder......................................................................................878
pub.sync:notify................................................................................................................. 878
pub.sync:shutdown.......................................................................................................... 879
pub.sync:wait................................................................................................................... 879
Synchronization Folder............................................................................................................... 881
Summary of Elements in this Folder......................................................................................882
pub.synchronization.latch:closeLatch.............................................................................. 882
pub.synchronization.latch:isLatchClosed.........................................................................883
pub.synchronization.latch:openLatch...............................................................................884
pub.synchronization.xref:createXReference.................................................................... 885
pub.synchronization.xref:deleteByObjectId......................................................................886
pub.synchronization.xref:deleteXReference.................................................................... 886
pub.synchronization.xref:getCanonicalKey......................................................................887
pub.synchronization.xref:getNativeId...............................................................................888
pub.synchronization.xref:insertXReference..................................................................... 889
Trigger Folder...............................................................................................................................891
Summary of Elements in this Folder......................................................................................892
pub.trigger:createJMSTrigger.......................................................................................... 893
pub.trigger:createTrigger..................................................................................................907
pub.trigger:deleteJMSTrigger...........................................................................................916
pub.trigger:deleteTrigger..................................................................................................916
pub.trigger:disableJMSTriggers....................................................................................... 917
pub.trigger:enableJMSTriggers........................................................................................919
pub.trigger:resourceMonitoringSpec................................................................................920
pub.trigger:resumeProcessing......................................................................................... 921
pub.trigger:resumeRetrieval.............................................................................................924
pub.trigger:suspendJMSTriggers..................................................................................... 926
pub.trigger:suspendProcessing....................................................................................... 928
pub.trigger:suspendRetrieval........................................................................................... 930
TX Folder...................................................................................................................................... 933

webMethods Integration Server Built-In Services Reference Version 9.6

18

M
Table of Contents

Summary of Elements in this Folder......................................................................................934

pub.tx:init..........................................................................................................................934
pub.tx:shutdown...............................................................................................................935
pub.tx:resetOutbound...................................................................................................... 935
UniversalName Folder................................................................................................................. 937
Summary of Elements in this Folder......................................................................................938
pub.universalName:find................................................................................................... 938
pub.universalName:findDocumentType........................................................................... 939
pub.universalName:list.....................................................................................................939
pub.universalName:listAll.................................................................................................940
Utils Folder................................................................................................................................... 943
Summary of Elements in this Folder......................................................................................944
pub.utils:deepClone......................................................................................................... 944
pub.utils:executeOSCommand........................................................................................ 945
pub.utils:generateUUID....................................................................................................947
pub.utils:getServerProperty............................................................................................. 947
pub.utils.ws:setCompatibilityModeFalse.......................................................................... 947
VCS Folder....................................................................................................................................953
Summary of Elements in this Folder......................................................................................954
pub.vcs.admin:getUsers.................................................................................................. 954
pub.vcs.admin:removeCurrentUser................................................................................. 955
pub.vcs.admin:removeMultipleUsers............................................................................... 956
pub.vcs.admin:setCurrentUser........................................................................................ 956
pub.vcs.admin:setMultipleUsers...................................................................................... 957
XML Folder................................................................................................................................... 959
Summary of Elements in this Folder......................................................................................960
pub.xml:documentToXMLString....................................................................................... 961
pub.xml:freeXMLNode..................................................................................................... 968
pub.xml:getNextXMLNode............................................................................................... 969
pub.xml:getXMLNodeIterator........................................................................................... 970
pub.xml:getXMLNodeType...............................................................................................973
pub.xml:loadEnhancedXMLNode.................................................................................... 973
pub.xml:loadXMLNode.....................................................................................................983
pub.xml:queryXMLNode.................................................................................................. 991
pub.xml:xmlNodeToDocument......................................................................................... 994
pub.xml:xmlStringToEnhancedXMLNode...................................................................... 1004
pub.xml:xmlStringToXMLNode.......................................................................................1008
XSLT Folder................................................................................................................................ 1011
Summary of Elements in this Folder....................................................................................1012
pub.xslt.Transformations:transformSerialXML............................................................... 1012
pub.xslt.Cache:removeAllTemplates..............................................................................1015
pub.xslt.Cache:removeTemplate....................................................................................1016
webMethods Integration Server Built-In Services Reference Version 9.6

19

M
Table of Contents

Index............................................................................................................................................ 1017

webMethods Integration Server Built-In Services Reference Version 9.6

20

Odd Header

About this Guide

The webMethods Integration Server Built-In Services Reference describes the built-in services
provided with a standard installation of the webMethods Integration Server. Services
are also installed with webMethods add-on packages, such as adapters and monitoring
tools. You will nd documentation for those services in the user guide provided with the
add-on product.
Note: This guide describes features and functionality that may or may not be available
with your licensed version of webMethods Integration Server. For information about
the licensed components for your installation, see the Settings > License page in the
webMethods Integration Server Administrator.
The descriptions in this book are divided into the following folders. These folders reside
in the WmPublic package, unless specied otherwise.
Folder

Contains services you use to

ART Folder

(WmART package) Manage adapter components,

including connections, adapter services, listeners, and
notications.

Cache Folder

Perform tasks on caches.

Client Folder

Formulate and submit requests to HTTP, FTP, e-mail,

and LDAP servers.

Date Folder

Generate and format date values.

Db Folder

(WmDB package) Access JDBC-enabled databases.

The webMethods Adapter for JDBC also provides
services that perform operations against JDBC-enabled
databases. See the webMethods Adapter for JDBC
Installation and Users Guide for information.

Document Folder

Perform operations on documents in the pipeline.

Event Folder

Build audit and event handler services.

File Folder

Perform operations on the local le system.

webMethods Integration Server Built-In Services Reference Version 9.6

21

Even Header

Folder

Contains services you use to

Flat File Folder

(WmFlatFile package) Convert between Flat File

documents and IS documents.

Flow Folder

Perform debugging and utility-type tasks in a ow

service.

Hashtable Folder

Create, update, and get information about the hashtable.

IO Folder

Convert data between byte[ ] and InputStream

representations.

JDBC Folder

Obtain information about Integration Server JDBC pools.

JMS Folder

Send and receive JMS messages.

JSON Folder

Parse JSON content in the pipeline.

List Folder

Retrieve, replace, or add elements in an Object List,

Document List, or String List; convert String Lists to
Document Lists.

Math Folder

Add, subtract, multiply, or divide string-based numeric

values.

Metadata Folder

Publish metadata about Integration Server packages and

administrative assets to the CentraSite shared registry.

MIME Folder

Create MIME messages and extract information from

MIME messages.

OAuth Folder

Authorize a client application to access data on

Integration Server using the OAuth 2.0 Authorization
Framework.

Packages Folder

Install, load, and/or alter the status of a package on the

Integration Server.

PKI Folder

(WmPKI package) Create and verify PKCS#7 signatures

with PKI proles and create and process S/MIME
messages using PKI proles.

webMethods Integration Server Built-In Services Reference Version 9.6

22

Odd Header

Folder

Contains services you use to

Publish Folder

Publish and deliver documents to other Integration

Servers via webMethods Universal Messaging or
webMethods Broker.

Remote Folder

Invoke services on remote webMethods Integration

Servers.

Replicator Folder

Replicate packages across webMethods Integration

Servers.

Report Folder

Apply an output template to the values in the pipeline.

Scheduler Folder

Schedule services to execute at the times you specify.

Schema Folder

Validate objects or values in the pipeline.

Security Folder

Control which client certicates are sent to other services

and digitally sign data and process digital signatures.
Store and retrieve outbound passwords to access secure
resources.

SMIME Folder

Create digitally signed and/or encrypted MIME

messages. Process signed and encrypted MIME
messages.

SOAP Folder

Send, receive, and retrieve data from SOAP messages.

Register custom SOAP processors.

Storage Folder

Create, close, delete, and register repository data stores.

Insert and retrieve information from data stores.

String Folder

Perform string manipulation and substitution

operations.

Sync Folder

Coordinate the execution of services.

Synchronization
Folder

Perform latching and cross-referencing operations in a

publish-and-subscribe integration.

Trigger Folder

Create and delete triggers and manage document

retrieval and document processing for individual

webMethods Integration Server Built-In Services Reference Version 9.6

23

Even Header

Folder

Contains services you use to

webMethods messaging triggers. Create, delete, enable,
disable, or suspend one or more JMS triggers.

TX Folder

Perform administrative tasks for guaranteed delivery

transactions.

UniversalName
Folder

List the contents of the Universal Registry and look up

services by their universal names.

Utils Folder

Retrieve the values of server properties

VCS Folder

Manage user associations for the VCS Integration

feature.

XML Folder

Perform operations on XML documents.

XSLT Folder

Transform an XML stream into a byte array, le, or XML

node, and to maintain the XSLT stylesheet cache.

Built-in services generally have the following default access permissions:

For this type of
permission...

Built-in services are assigned to this ACL...

List

Developers

Members of the Developers ACL can see, in

webMethods Integration Server or Software AG
Designer, that a service exists.

Read

WmPrivate

The WmPrivate ACL is a virtual ACL designed to

protect the proprietary code in the built-in services.
As this ACL has no members, no user can edit a
service or view its source.

Write

WmPrivate

Execute

Internal

Members of the Internal ACL can execute a service.

webMethods Integration Server Built-In Services Reference Version 9.6

24

Odd Header

These default access permissions cannot be changed (that is, another ACL cannot be
selected).

Document Conventions
Convention

Description

Bold

Identies elements on a screen.

Narrowfont

Identies storage locations for services on webMethods

Integration Server, using the convention folder.subfolder:service .

UPPERCASE

Identies keyboard keys. Keys you must press simultaneously

are joined with a plus sign (+).

Italic

Identies variables for which you must supply values specic to

your own situation or environment. Identies new terms the rst
time they occur in the text.

Monospace
font

Identies text you must type or messages displayed by the

system.

{}

Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.

Separates two mutually exclusive choices in a syntax line. Type

one of these choices. Do not type the | symbol.

[]

Indicates one or more options. Type only the information inside

the square brackets. Do not type the [ ] symbols.

...

Indicates that you can type multiple options of the same type.
Type only the information. Do not type the ellipsis (...).

Documentation Installation
You can download the product documentation using the Software AG Installer. The
documentation is downloaded to a central directory named _documentation in the main
installation directory (SoftwareAG by default).

webMethods Integration Server Built-In Services Reference Version 9.6

25

Even Header

Online Information
SoftwareAG Documentation Website
You can nd documentation on the Software AG Documentation website at hp://
documentation.softwareag.com. The site requires Empower credentials. If you do not
have Empower credentials, you must use the TECHcommunity website.
Software AG Empower Product Support Website
You can nd product information on the Software AG Empower Product Support
website at hps://empower.softwareag.com.
To submit feature/enhancement requests, get information about product availability,
and download products and certied samples, go to Products.
To get information about xes and to read early warnings, technical papers, and
knowledge base articles, go to the Knowledge Center.
Software AG TECHcommunity
You can nd documentation and other technical information on the Software AG
TECHcommunity website at hp://techcommunity.softwareag.com. You can:
Access product documentation, if you have TECHcommunity credentials. If you do
not, you will need to register and specify "Documentation" as an area of interest.
Access articles, demos, and tutorials.
Use the online discussion forums, moderated by Software AG professionals, to
ask questions, discuss best practices, and learn how other customers are using
Software AG technology.
Link to external websites that discuss open standards and web technology.

webMethods Integration Server Built-In Services Reference Version 9.6

26

Odd Header
ART Folder

1 ART Folder
Summary of Elements in this Folder ...........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

28

27

Even Header
ART Folder

You use the elements in the art folder to manage adapter components, including
connections, adapter services, listeners, and notications.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.art:listRegisteredAdapters

WmART. Returns the display

name and adapter type name of
all registered adapters.

pub.art.connection:disableConnection

WmART. Disables a connection

node.

pub.art.connection:enableConnection

WmART. Enables an existing

connection node.

pub.art.connection:getConnectionStatistics

WmART. Returns current usage

statistics for a connection node.

pub.art.connection:listAdapterConnections

WmART. Lists connection nodes

associated with a specied
adapter.

pub.art.connection:queryConnectionState

WmART. Returns the current

connection state (enabled/
disabled) and error status for a
connection node.

pub.art.listener:disableListener

WmART. Disables a listener.

pub.art.listener:enableListener

WmART. Enables an existing

listener.

pub.art.listener:listAdapterListeners

WmART. Lists listeners

associated with a specied
adapter.

pub.art.listener:queryListenerState

WmART. Returns the current

state for a listener.

webMethods Integration Server Built-In Services Reference Version 9.6

28

Odd Header
ART Folder

Element

Package and Description

pub.art.listener:resumeListener

WmART. Resumes a specied

listener.

pub.art.listener:setListenerNodeConnection

WmART. Changes the connection

node used by a specied listener.

pub.art.listener:suspendListener

WmART. Suspends a specied

listener.

pub.art.notification:disableListenerNotification

WmART. Disables a listener

notication.

pub.art.notification:disablePollingNotification

WmART. Disables a polling

notication.

pub.art.notification:enableListenerNotification

WmART. Enables an existing

listener notication.

pub.art.notification:enablePollingNotification

WmART. Enables an existing

polling notication.

pub.art.notification:listAdapterListenerNotifications

WmART. Lists the listener

notications associated with a
specied adapter.

pub.art.notification:listAdapterPollingNotifications

WmART. Lists the polling

notications associated with a
specied adapter.

pub.art.notification:queryListenerNotificationState

WmART. Returns the current

state (enabled/disabled) for a
listener notication.

pub.art.notification:queryPollingNotificationState

WmART. Returns the current

state for a polling notication.

pub.art.notification:resumePollingNotification

WmART. Resumes a specied

polling notication node.

pub.art.notification:setListenerNotificationNodeListener

WmART. Changes the listener

used by a specied listener
notication.

webMethods Integration Server Built-In Services Reference Version 9.6

29

Even Header
ART Folder

Element

Package and Description

pub.art.notification:setPollingNotificationNodeConnection

WmART. Changes the connection

node used by a specied polling
notication.

pub.art.notification:suspendPollingNotification

WmART. Suspends a specied

polling notication.

pub.art.service:listAdapterServices

WmART. Lists adapter services

associated with a specied
adapter.

pub.art.service:setAdapterServiceNodeConnection

WmART. Changes the connection

node used by a specied adapter
service.

pub.art.transaction:commitTransaction

WmART. Commits an explicit

transaction.

pub.art.transaction:rollbackTransaction

WmART. Rolls back an explicit

transaction.

pub.art.transaction:setTransactionTimeout

WmART. Manually sets a

transaction timeout interval for
implicit and explicit transactions.

pub.art.transaction:startTransaction

WmART. Starts an explicit

transaction.

pub.art:listRegisteredAdapters
WmART. Returns the display name and adapter type name of all registered adapters.
Input Parameters
None.
Output Parameters
registeredAdapterList

Document List Information for each adapter registered with

the WmART package.

webMethods Integration Server Built-In Services Reference Version 9.6

30

Odd Header
ART Folder

Key

Description

adapterDisplayName

String The localized name that the

Integration Server Administrator
displays.

adapterTypeName

String The name of the adapter as

registered with the WmART package.
This value can be used as input
for the inventory services that take
adapterTypeName as input.

pub.art.connection:disableConnection
WmART. Disables a connection node.
Input Parameters
connectionAlias

String Name of the connection node you want to disable.

Output Parameters
None.
See Also
pub.art.connection:enableConnection

pub.art.connection:enableConnection
WmART. Enables an existing connection node.
Input Parameters
connectionAlias

String Name of the connection node you want to enable.

Output Parameters
None.
See Also
pub.art.connection:disableConnection

webMethods Integration Server Built-In Services Reference Version 9.6

31

Even Header
ART Folder

pub.art.connection:getConnectionStatistics
WmART. Returns current usage statistics for a connection node.
Input Parameters
aliasName

String Name of the connection node for which you want usage
statistics returned.

Output Parameters
connectionStatistics

Document List Information for each connection node.

Key

Description

TotalConnections

Integer Current number of connection

instances.

BusyConnections

Integer Number of connections currently

in use by services, notications, and
listeners.

FreeConnections

Integer Total number of connections

created and available for use.

TotalHits

Integer Number of times this connection

node successfully provided connections
since the last reset.

TotalMisses

Integer Number of times this connection

node unsuccessfully provided
connections since the last reset (when the
request timed out).

See Also
pub.art.connection:queryConnectionState

pub.art.connection:listAdapterConnections
WmART. Lists connection nodes associated with a specied adapter.

webMethods Integration Server Built-In Services Reference Version 9.6

32

Odd Header
ART Folder

Input Parameters
adapterTypeName

String The name of the adapter as registered with the WmART

package.

Output Parameters
connectionDataList

Document List Information for each connection node registered

with the specied adapter.
Key

Description

connectionAlias

String The name of the connection node.

packageName

String The name of the package in which

the connection node resides.

connectionState

String Current state of the connection node.

The state will have one of these values:
disabled - Connection node is disabled
enabled - Connection node is enabled.
shuttingdown - Connection node is in the

process of shuing down.

unknown - Connection node is registered

but has not yet established its state.

See Also
pub.art:listRegisteredAdapters
pub.art.connection:queryConnectionState

pub.art.connection:queryConnectionState
WmART. Returns the current connection state (enabled/disabled) and error status for a
connection node.

webMethods Integration Server Built-In Services Reference Version 9.6

33

Even Header
ART Folder

Input Parameters
connectionAlias

String Name of the connection node for which you want the
connection state and error status returned.

Output Parameters
connectionState

String Current connection state (enabled/disabled).

hasError

Boolean Flag indicating if any error was detected on

connection. The values are:
true if an error was detected.
false if no error was detected.

See Also
pub.art.connection:getConnectionStatistics
pub.art.connection:enableConnection
pub.art.connection:disableConnection

pub.art.listener:disableListener
WmART. Disables a listener.
Input Parameters
listenerName

String Name of the listener you want to disable. The listener

should have a state of enabled or suspended.

forceDisable

String Optional. Flag to disable the listener regardless of

whether it is still waiting for data from a back-end resource.
The string may have one of these values:
true to disable the listener.
false to keep the listener enabled.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

34

Odd Header
ART Folder

See Also
pub.art.listener:enableListener

pub.art.listener:enableListener
WmART. Enables an existing listener.
Input Parameters
listenerName

String Name of the listener you want to enable.

Output Parameters
None.
Usage Notes
If you do not enable the connection resource associated with the listener, this service will
return without performing any action, and the listener will remain disabled. Therefore,
you should invoke pub.art.listener:queryListenerState before calling this service to conrm
that the listener has been enabled.
See Also
pub.art.listener:queryListenerState
pub.art.listener:disableListener

pub.art.listener:listAdapterListeners
WmART. Lists listeners associated with a specied adapter.
Input Parameters
adapterTypeName

String The name of the adapter as registered with the WmART

package.

Output Parameters
listenerDataList

Document List Information for each listener registered with the

specied adapter.

webMethods Integration Server Built-In Services Reference Version 9.6

35

Even Header
ART Folder

Key

Description

listenerNodeName

String The name of the listener.

packageName

String The name of the package in which

the listener resides.

listenerEnabled

String Current state of the listener. The

state will have one of these values:
disabled if the listener is disabled.
enabled if the listener is enabled.
enablePending if the listener is in the

process of starting.

disablePending if the listener is in the

process of disabling.

suspended if the listener is suspended.

suspendPending if the listener is in the

process of suspending.
See Also
pub.art:listRegisteredAdapters
pub.art.listener:queryListenerState

pub.art.listener:queryListenerState
WmART. Returns the current state for a listener.
Input Parameters
listenerName

String Name of the listener for which you want the current
state returned.

Output Parameters
listenerState

String Current state of the listener. The state will have one of
these values:
disabled if the listener is disabled.
enabled if the listener is enabled.

webMethods Integration Server Built-In Services Reference Version 9.6

36

Odd Header
ART Folder

enablePending if the listener is in the process of starting.

disablePending if the listener is in the process of disabling.
suspended if the listener is suspended.
suspendPending if the listener is in the process of

suspending.
See Also
pub.art.listener:enableListener
pub.art.listener:disableListener

pub.art.listener:resumeListener
WmART. Resumes a specied listener.
Input Parameters
listenerName

String The name of the suspended listener you want to resume.

The service returns an error if you specify an invalid listener.

Output Parameters
None.
Usage Notes
If the requested transition is not valid (for example, trying to resume a disabled listener
or a listener that is already resumed), the service ignores the request.
After you use this service, you can use pub.art.listener:queryListenerState to verify
pub.art.listener:resumeListener correctly changed the state of the listener.
See Also
pub.art.listener:queryListenerState
pub.art.listener:suspendListener

pub.art.listener:setListenerNodeConnection
WmART. Changes the connection node used by a specied listener.

webMethods Integration Server Built-In Services Reference Version 9.6

37

Even Header
ART Folder

Input Parameters
listenerName

String Name of the listener for which you want to change the
connection node.

connectionAlias

String Name of the new connection node to use with the

listener.

Output Parameters
None.
Usage Notes
Calling this service for a listener that is disabled is permied.
Calling this service for a listener that is suspended changes the state of the listener to
disabled. The user must enable the listener before using it.
See Also
pub.art.listener:disableListener

pub.art.listener:suspendListener
WmART. Suspends a specied listener.
Input Parameters
listenerName

String The name of the listener you want to suspend. The

service returns an error if you specify an invalid listener.

Output Parameters
None.
Usage Notes
If the requested transition is not valid (for example, trying to suspend a disabled listener
or a listener that is already suspended), the service ignores the request.
After you use this service, you can use pub.art.listener:queryListenerState to verify
pub.art.listener:suspendListener correctly changed the state of the listener.
See Also
pub.art.listener:queryListenerState

webMethods Integration Server Built-In Services Reference Version 9.6

38

Odd Header
ART Folder

pub.art.listener:resumeListener

pub.art.notification:disableListenerNotification
WmART. Disables a listener notication.
Input Parameters
noticationName

String The name of the listener notication you want to disable.

Output Parameters
None.
See Also
pub.art.notification:enableListenerNotification

pub.art.notification:disablePollingNotification
WmART. Disables a polling notication.
Input Parameters
noticationName

String The name of the polling notication you want to disable.

The polling notication should have a state of enabled or
suspended.

Output Parameters
None.
See Also
pub.art.notification:enablePollingNotification

pub.art.notification:enableListenerNotification
WmART. Enables an existing listener notication.

webMethods Integration Server Built-In Services Reference Version 9.6

39

Even Header
ART Folder

Input Parameters
noticationName

String The name of the listener notication you want to enable.

Output Parameters
None.
See Also
pub.art.notification:disableListenerNotification

pub.art.notification:enablePollingNotification
WmART. Enables an existing polling notication.
Input Parameters
noticationName

String Name of the polling notication you want to enable.

Output Parameters
None.
Usage Notes
You must schedule the polling notication before you can run this service. See your
adapter user documentation for instructions to schedule the polling notication.
See Also
pub.art.notification:disablePollingNotification

pub.art.notification:listAdapterListenerNotifications
WmART. Lists the listener notications associated with a specied adapter.
Input Parameters
adapterTypeName

String The name of the adapter as registered with the WmART

package.

webMethods Integration Server Built-In Services Reference Version 9.6

40

Odd Header
ART Folder

Output Parameters
noticationDataList

Document List Information for each listener notication

registered with the specied adapter.
Key

Description

noticationNodeName

String The name of the listener

notication.

packageName

String The name of the package in

which the listener notication resides.

noticationEnabled

String The current state of the listener

notication. The state will have one of
these values:
no if the listener notication is

disabled.

yes if the listener notication is

enabled.
See Also
pub.art:listRegisteredAdapters
pub.art.notification:queryListenerNotificationState

pub.art.notification:listAdapterPollingNotifications
WmART. Lists the polling notications associated with a specied adapter.
Input Parameters
adapterTypeName

String The name of the adapter as registered with the WmART

package.

Output Parameters
noticationDataList

Document List Information for each polling notication

registered with the specied adapter.

webMethods Integration Server Built-In Services Reference Version 9.6

41

Even Header
ART Folder

Key

Description

noticationNodeName

String The name of the polling

notication.

packageName

String The name of the package in

which the polling notication resides.

noticationEnabled

String The current state of the polling

notication. The state will have one of
these values:
no if the polling notication is

disabled.

yes if the polling notication is

enabled.

pending if the polling notication is

in the process of shuing down.

suspended if the polling notication

is suspended.
See Also
pub.art:listRegisteredAdapters
pub.art.notification:queryPollingNotificationState

pub.art.notification:queryListenerNotificationState
WmART. Returns the current state (enabled/disabled) for a listener notication.
Input Parameters
noticationName

String The name of the listener notication for which you want
the current state (enabled/disabled) returned.

Output Parameters
noticationState

String The current state (enabled/disabled) for the listener

notication.

webMethods Integration Server Built-In Services Reference Version 9.6

42

Odd Header
ART Folder

See Also
pub.art.notification:enableListenerNotification
pub.art.notification:disableListenerNotification

pub.art.notification:queryPollingNotificationState
WmART. Returns the current state for a polling notication.
Input Parameters
noticationName

String The name of the polling notication for which you want
the current state and schedule seings returned.

Output Parameters
noticationState

String The current state (enabled, disabled, pending disable,

pending suspend, or suspended) for the polling notication.

scheduleSeings

IData Object that contains the notication's schedule seings as

follows:
Key

Description

noticationInterval

Integer Polling frequency of the

notication.

noticationOverlap

Boolean Flags whether the

notication can overlap. The values
are:
true if the notication can overlap.
false if the notication cannot

overlap.
noticationImmediate

Boolean Flags whether the

notication can re immediately. The
values are:
true if the notication can re

immediately.

webMethods Integration Server Built-In Services Reference Version 9.6

43

Even Header
ART Folder

false if the notication cannot re

immediately.
See Also
pub.art.notification:enablePollingNotification
pub.art.notification:disablePollingNotification

pub.art.notification:resumePollingNotification
WmART. Resumes a specied polling notication node.
Input Parameters
noticationName

String The name of the polling notication you want to resume.

The service returns an error if you specify an invalid polling
notication.

Output Parameters
None.
Usage Notes
If the requested transition is not valid (for example, trying to resume a disabled polling
notication or a polling notication that is already resumed), the service ignores the
request.
After you use this service, you can use pub.art.notification:queryPollingNotificationState to
verify pub.art.notification:resumePollingNotification correctly changed the state of the polling
notication to enabled.
See Also
pub.art.notification:queryPollingNotificationState
pub.art.notification:suspendPollingNotification

pub.art.notification:setListenerNotificationNodeListener
WmART. Changes the listener used by a specied listener notication.

webMethods Integration Server Built-In Services Reference Version 9.6

44

Odd Header
ART Folder

Input Parameters
noticationName

String Name of the listener notication for which you want to

change the listener.

listenerNode

String Name of the new listener to use with the listener

notication.

Output Parameters
None.
Usage Notes
This service returns an error if the listener notication is enabled.
You can use this service for synchronous and asynchronous listener notications.
See Also
pub.art.notification:disableListenerNotification

pub.art.notification:setPollingNotificationNodeConnection
WmART. Changes the connection node used by a specied polling notication.
Input Parameters
noticationName

String Name of the polling notication for which you want to

change the connection node.

connectionAlias

String Name of the new connection node to use with the

polling notication.

Output Parameters
None.
Usage Notes
The polling notication must be in a disabled or suspended state before you call this
service. This service returns an error if the polling notication is enabled.
If you use this service on a suspended polling notication, the service changes the state
of the polling notication to disabled.

webMethods Integration Server Built-In Services Reference Version 9.6

45

Even Header
ART Folder

See Also
pub.art.notification:disablePollingNotification

pub.art.notification:suspendPollingNotification
WmART. Suspends a specied polling notication.
Input Parameters
noticationName

String The name of the polling notication you want to

suspend. The service returns an error if you specify an invalid
polling notication.

Output Parameters
None.
Usage Notes
If the requested transition is not valid (for example, trying to suspend a disabled polling
notication or a polling notication that is already suspended), the service ignores the
request.
After you use this service, you can use pub.art.notification:queryPollingNotificationState to
verify pub.art.notification:suspendPollingNotification correctly changed the state of the polling
notication to suspended.
See Also
pub.art.notification:queryPollingNotificationState
pub.art.notification:resumePollingNotification

pub.art.service:listAdapterServices
WmART. Lists adapter services associated with a specied adapter.
Input Parameters
adapterTypeName

String The name of the adapter as registered with the WmART

package.

webMethods Integration Server Built-In Services Reference Version 9.6

46

Odd Header
ART Folder

Output Parameters
serviceDataList

Document List Information for each adapter service registered

with the specied adapter.
Key

Description

serviceNodeName

String The name of the adapter service.

packageName

String The name of the package in which

the adapter service resides.

See Also
pub.art:listRegisteredAdapters

pub.art.service:setAdapterServiceNodeConnection
WmART. Changes the connection node used by a specied adapter service.
Input Parameters
serviceName

String Name of an existing adapter service for which you want

to change the connection node.

connectionAlias

String Name of the new connection node to use with the

adapter service.

Output Parameters
None.
Usage Notes
The new connection node must be enabled before you call this service.
See Also
pub.art.connection:enableConnection

pub.art.transaction:commitTransaction
WmART. Commits an explicit transaction.

webMethods Integration Server Built-In Services Reference Version 9.6

47

Even Header
ART Folder

Input Parameters
commitTransactionInput

Document List Information for each commit request.

Key

Description

transactionName

String The name of an explicit

transaction that you want to commit.
The transactionName must have
been previously used in a call to
pub.art.transaction:startTransaction.
This value must be mapped
from the most recent
pub.art.transaction:startTransaction that has
not previously been commied or
rolled back.

Output Parameters
None.
Usage Notes
This service is available only if your adapter supports built-in transaction management
services, which you can conrm by checking the user guide for the adapter.
This service must be used in conjunction with the pub.art.transaction:startTransaction
service. If the transactionName parameter was not provided in a prior call to
pub.art.transaction:startTransaction, a run-time error will be returned.
See Also
pub.art.transaction:startTransaction
pub.art.transaction:rollbackTransaction

pub.art.transaction:rollbackTransaction
WmART. Rolls back an explicit transaction.
Input Parameters
rollbackTransactionInput

Document List Information for each rollback request.

Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

48

Odd Header
ART Folder

transactionName

String The name of an explicit

transaction that you want to roll
back. The transactionName must
have been previously used in a call
to pub.art.transaction:startTransaction.
This value must be mapped
from the most recent
pub.art.transaction:startTransaction that
has not previously been commied
or rolled back.

Output Parameters
None.
Usage Notes
This service is available only if your adapter supports built-in transaction management
services, which you can conrm by checking the adapter's user guide.
This service must be used in conjunction with the pub.art.transaction:startTransaction
service. If the given transactionName parameter was not provided in a prior call to
pub.art.transaction:startTransaction, a run-time error will be returned.
See Also
pub.art.transaction:startTransaction
pub.art.transaction:commitTransaction

pub.art.transaction:setTransactionTimeout
WmART. Manually sets a transaction timeout interval for implicit and explicit
transactions.
Input Parameters
timeoutSeconds

Integer The number of seconds that the implicit or explicit

transaction stays open before the transaction manager marks it
for rollback.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

49

Even Header
ART Folder

Usage Notes
This service is available only if your adapter supports built-in transaction management
services, which you can conrm by checking the user guide for the adapter.
When you use this service, you are temporarily overriding the Integration Server
transaction timeout interval.
You must call this service within a ow before the start of any implicit or explicit
transactions. Implicit transactions start when you call an adapter service in a ow.
Explicit transactions start when you call the pub.art.transaction:startTransaction service.
If the execution of a transaction takes longer than the transaction timeout interval, all
transacted operations are rolled back.
This service only overrides the transaction timeout interval for the ow service in which
you call it.
See Also
pub.art.transaction:startTransaction

pub.art.transaction:startTransaction
WmART. Starts an explicit transaction.
Input Parameters
startTransactionInput

Document List Information for each start transaction

request.
Key

Description

transactionName

String Optional. Species the

name of the transaction to be
started. If you leave this parameter
blank, Integration Server will
generate a name for you. In
most implementations it is not
necessary to provide your own
transaction name.

Output Parameters
startTransactionOutput

Document List Information for each start transaction

request.

webMethods Integration Server Built-In Services Reference Version 9.6

50

Odd Header
ART Folder

Key

Description

transactionName

String The name of the transaction

the service just started.

Usage Notes
This service is available only if your adapter supports built-in transaction management
services, which you can conrm by checking the user guide for the adapter.
This service is intended for use with the pub.art.transaction:commitTransaction or
pub.art.transaction:rollbackTransaction service. The transactionName value returned by a
call to this service can be provided to pub.art.transaction:commitTransaction (to commit the
transaction) or pub.art.transaction:rollbackTransaction (to roll back the transaction).
See Also
pub.art.transaction:commitTransaction
pub.art.transaction:rollbackTransaction

webMethods Integration Server Built-In Services Reference Version 9.6

51

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

52

Odd Header
Cache Folder

2 Cache Folder
About Checkpoint Restart ............................................................................................................

54

Summary of Elements in this Folder ...........................................................................................

55

webMethods Integration Server Built-In Services Reference Version 9.6

53

Even Header
Cache Folder

You use the elements in the cache folder to place data in a cache and retrieve it again
later. You can also use the services in the cache folder to perform administrative
operations such as enabling, disabling, and clearing a cache, or to implement checkpoint
restart in services you write. Integration Server uses Ehcache internally for all of the
services in the cache folder. Before using these services, you need create a cache manager
and cache using Integration Server Administrator. For more information about creating
a cache manager and cache, see webMethods Integration Server Administrators Guide.
Note: The key you use for the services in the cache folder must be an object that
overrides the equals() method from java.lang.Object. Failure to use such an object can
cause the service to return incorrect results.
Note: You cannot use an IS document object as a key for storing objects in the cache
because IS document objects do not implement the equals() method.

About Checkpoint Restart

You can use the pub.cache services to implement checkpoint restart in services that
you write to make them more robust. You use the pub.cache services to write state
information and other pertinent data to the cache. If the Integration Server on which
your service is executing becomes unavailable, your service will be able to check the
state information in the cache and resume processing at the point where the service was
interrupted.
Note: The pub.cache services are a tool for maintaining state information for the short
term. It is up to the developer of the services to make sure they keep track of state
information and correctly handle restarts.
The following diagram shows the logic of a ow service that uses checkpoint restart.

webMethods Integration Server Built-In Services Reference Version 9.6

54

Odd Header
Cache Folder

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.cache:containsKey

WmPublic. Checks whether an element

with the specied key exists in the
cache.

webMethods Integration Server Built-In Services Reference Version 9.6

55

Even Header
Cache Folder

Element

Package and Description

pub.cache:get

WmPublic. Retrieves the value of a

cached element for the specied key.

pub.cache:getKeys

WmPublic. Retrieves the keys of all

elements available in the cache.

pub.cache:put

WmPublic. Populates a cached element

with a specied key-value pair.

pub.cache:remove

WmPublic. Removes the cached

element associated with the specied
key.

pub.cache:search

WmPublic. Searches through an

indexed cache and returns the results.

pub.cache.admin:clearAllCaches

WmPublic. Deletes all of the elements

from all caches contained in the
specied cache manager.

pub.cache.admin:clearCache

WmPublic. Deletes all elements from

the specied cache.

pub.cache.admin:disableCache

WmPublic. Disables a cache.

pub.cache.admin:enableCache

WmPublic. Enables a cache.

pub.cache.admin:evictExpiredElements

WmPublic. Deletes all of the expired

elements from a cache.

pub.cache.admin:isCacheDisabled

WmPublic. Checks whether the cache is

disabled.

pub.cache.atomic:putIfAbsent

WmPublic. Adds an element to the

cache if the cache does not contain an
element with the specied key.

pub.cache.atomic:remove

WmPublic. Removes the cached

element associated with the specied
key and value.

webMethods Integration Server Built-In Services Reference Version 9.6

56

Odd Header
Cache Folder

Element

Package and Description

pub.cache.atomic:replace

WmPublic. Replaces the cached

element value with the supplied value.

pub.cache.atomic:replaceIfKeyExists

WmPublic. Replaces the cached

element if an element for the specied
key exists in a cache.

pub.cache.bulk:isClusterBulkLoadEnabled

WmPublic. Checks whether the cache

on at least one Integration Server node
in the Terracoa Server Array cluster is
enabled for bulk loading.

pub.cache.bulk:isNodeBulkLoadEnabled

WmPublic. Checks whether the cache

of the current Integration Server node
in the Terracoa Server Array cluster is
bulk-load enabled.

pub.cache.bulk:setNodeBulkLoadEnabled

WmPublic. Enables or disables bulk

loading mode in the current Integration
Server node for the cache.

pub.cache.bulk:waitUntilClusterBulkLoadComplete

WmPublic. Indicates whether

Integration Server delays execution of
the next step in a ow service until all
of the Integration Server nodes in the
Terracoa Server Array cluster disable
bulk loading for the cache.

pub.cache.lock:acquireLock

WmPublic. Acquires a lock on the

cached element that contains the
specied key.

pub.cache.lock:isLockedByCurrentThread

WmPublic. Checks whether the current

thread is holding a lock on the cached
element for the specied key.

pub.cache.lock:releaseLock

WmPublic. Releases a lock on the

element for the specied key.

webMethods Integration Server Built-In Services Reference Version 9.6

57

Even Header
Cache Folder

pub.cache:containsKey
WmPublic. Checks whether an element with the specied key exists in the cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the key. This parameter
is case sensitive.

key

Object Key of the element for whose existence you are

checking.

Output Parameters
found

String Indicates whether the key exists in the cache.

true indicates that the key exists in the cache.
false indicates that the key does not exist in the cache.

Usage Notes
The pub.cache:containsKey service does not verify whether the element is expired. If
the element of the specied key is expired, and the element is present in the cache,
pub.cache:containsKey returns found with a value of true.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache:get
WmPublic. Retrieves the value of a cached element for the specied key.

webMethods Integration Server Built-In Services Reference Version 9.6

58

Odd Header
Cache Folder

Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which to retrieve the element.

This parameter is case sensitive.

key

Object Key associated with the cached value.

useLoader

String Optional. Indicates whether to use a cache loader to

retrieve the element from the cache. Set to:
true to use a cache loader to retrieve the element if it is not

already in the cache.

Note: If useLoader is true and no loaders are congured for

the cache, Integration Server issues a ServiceException.
false to retrieve the element from the cache without a cache

loader. This is the default seing.

Output Parameters
value

Object Value of the element retrieved from the cache.

Usage Notes
If useLoader is set to false and pub.cache:get nds the key in the cache, the results contain
the value of the element. If the key does not exist in the cache, pub.cache:get returns a null
in the value parameter.
If useLoader is set to true and pub.cache:get cannot nd the specied key in the cache, it
uses the congured cache loader to nd the key in the system-of-record (SOR). If the
SOR contains the key, pub.cache:get returns the value of the element. If the key does not
exist in the SOR, pub.cache:get returns a null in the value parameter.
The pub.cache:get service returns a null in the value parameter if:
You run the service on a disabled cache.
The service cannot nd the specied key.
The element associated with the specied key is expired.
Integration Server issues a ServiceException in the following cases:
If useLoader is true and no loaders are congured for the cache.

webMethods Integration Server Built-In Services Reference Version 9.6

59

Even Header
Cache Folder

If you do not specify all required input parameters.

If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache:getKeys
WmPublic. Retrieves the keys of all elements available in the cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache.

This parameter is case sensitive.

cacheName

String Name of the cache from which to retrieve the keys. This
parameter is case sensitive.

excludeExpiredKeys

String Optional. Indicates whether the service results exclude

keys for expired elements. Set to:
true to exclude the keys of expired elements. This is the

default.

false to include the keys of all elements.

Output Parameters
keys

Object List List of keys of elements in the cache.

Usage Notes
Caution: Retrieving all of the keys from a cache is a memory-intensive activity. It is
possible for the list of available keys to be larger than the memory available on your
system. In such cases, Integration Server might issue an OutOfMemoryError and
become unresponsive.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

webMethods Integration Server Built-In Services Reference Version 9.6

60

Odd Header
Cache Folder

pub.cache:put
WmPublic. Populates a cached element with a specied key-value pair.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache in which to put the element. This

parameter is case sensitive.

key

Object Key of the cached element.

value

Object Value of the cached element.

useWriter

String Optional. Indicates whether to use a cache writer to

populate the value of the cached element in the system-ofrecord (SOR). Set to:
true to use a cache writer to add the value to the cached

element and the SOR.

false to add the value to the cached element without writing

to the SOR. This is the default seing.

Note: If the value already exists in the cache, pub.cache:put replaces

the value.
Output Parameters
None.
Usage Notes
If your cache is a distributed cache or is congured to use disk store or BigMemory, key
and value must be Java Serializable objects.
If the element with the specied key does not already exist in the cache, the pub.cache:put
service puts the element in the cache. If the element with the specied key already exists
in the cache, pub.cache:put updates the element with the specied value .
If you run pub.cache:put on a disabled cache, the cache discards the call.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.

webMethods Integration Server Built-In Services Reference Version 9.6

61

Even Header
Cache Folder

If useWriter is set to true and no writer is congured for the cache.

If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache:remove
WmPublic. Removes the cached element associated with the specied key.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which to remove the element.

This parameter is case sensitive.

key

Object Key of the element to remove.

Output Parameters
removed

String Indicates whether the element was removed.

true indicates that the element was removed from the cache.
false indicates that the element was not removed from the

cache.
Usage Notes

If the element associated with the specied key does not exist, pub.cache:remove returns
false for removed .
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

webMethods Integration Server Built-In Services Reference Version 9.6

62

Odd Header
Cache Folder

pub.cache:search
WmPublic. Searches through an indexed cache and returns the results. The
pub.cache:search service accepts the selection criteria as an IData object and performs the
search by converting the IData object to a search query of Ehcache.
Note: Before using this service, you must make the cache searchable. For more
information about making a cache searchable, see webMethods Integration Server
Administrators Guide.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which the search results are to
be returned. This parameter is case sensitive.

includeAributes

String Optional. List of aributes that should be included in the

search results.

includeKey

String Optional. Indicates whether or not the keys should be

returned as part of the search results.
true indicates that the keys should be returned as part of the

search results.

false indicates that the keys should not be returned as part

of the search results. This is the default.

Note: You should set this parameter to true only if the value is
required for your programming logic.
includeValue

String Optional. Indicates whether or not the values should be

returned as part of the search results.
true indicates that the values should be returned as part of

the search results.

false indicates that the values should not be returned as part

of the search results. This is the default.

Note: You should set this parameter to true only if the value is
required for your programming logic.

webMethods Integration Server Built-In Services Reference Version 9.6

63

Even Header
Cache Folder

criteria

Document A document (IData) that species the conditions

based on which the data in the cache is to be queried.
Value

Description

OP1

String or Document A string operand or

a nested document type that can be
evaluated by a logical operator.

OPR

String A logical (and, or, and not) or

comparison operator (between, gt (greater
than), eq (equal to), and so on).

OP2

String or Document A string operand or

a nested document type that can be
evaluated by a logical operator.

maxResults

String Optional. The maximum number of results to return. If

maxResults is not specied, Integration Server returns all the
results.

groupBy

String Optional. The unique values of specied aributes based

on which the search results are to be grouped. The aributes
that you specify for grouping the results must be included
in the list of aributes specied for the includeAributes
parameter.

orderBy

String Optional. The order in which the service results

are to be returned. Values for this parameter should be
specied as a two-dimensional string array (for example,
"name","ascending" or "age","descending").

aggregator

String Aggregator function such as Average, Count, Max,

Min, or Sum that you want to be applied on the search
results. Values for this parameter should be specied as a
two-dimensional string array (for example, "age","max" or
"income","average").

Output Parameters
results

Object List The returned results of the search.

Value

Description

webMethods Integration Server Built-In Services Reference Version 9.6

64

Odd Header
Cache Folder

Key

Object Conditional. The element key.

Returned only if includeKey is set to true.

Value

Object Conditional. The element value.

Returned only if includeValue is set to
true.

Result

Object The search results. Each element

in the cache that matches the specied
criteria will be returned as a result object.
The Result object contains aggregator
results and aribute values. The
aggregator results contain the values
of the aggregator functions and
aribute values contain the values of
aributes included in the includeAribute
parameter.

Usage Notes
By default a search will return an unlimited number of results. If too many results
are returned, Integration Server might issue an OutOfMemoryError and become
unresponsive. Limit the size of the results using the maxResults parameter.
Because the state of the cache can change between search executions, include
all of the aggregators to the search query at the same time, so that the returned
aggregators are of the same iteration of the cache.
A sample IData that you can specify as the criteria input parameter is given below.
The following input searches the personCache cache for entries, where age is greater
than 60 and gender is female.
IData idata = IDataFactory.create();
//Cache information
IDataMap map = new IDataMap(idata)
;
map.put("cacheManagerName", "SearchTestManager")
;
map.put("cacheName", "personCache")
;
map.put("includeKey", "true")
;
map.put("includeValue", "true") ;
//Condition 1 - Age > 60
IData input1 = IDataFactory.create()
;
IDataCursor cursor1 = input1.getCursor()
;
IDataUtil.put(cursor1, "OP1", "age")
;
IDataUtil.put(cursor1, "OPR", "gt")
;
IDataUtil.put(cursor1, "OP2", 60) ;
//Condition 2 - Gender == Female
IData input2 = IDataFactory.create()
;
IDataCursor cursor2= input2.getCursor()
;
IDataUtil.put(cursor2, "OP1", "gender")
;
IDataUtil.put(cursor2, "OPR", "eq")
;
IDataUtil.put(cursor2, "OP2", Person.Gender.FEMALE) ;
//Joining conditions, condition 1 && condition 2
IData input3 = IDataFactory.create()
;

webMethods Integration Server Built-In Services Reference Version 9.6

65

Even Header
Cache Folder

IDataCursor cursor3 = input3.getCursor()

;
IDataUtil.put(cursor3, "OP1", input1)
;
IDataUtil.put(cursor3, "OPR", "AND")
;
IDataUtil.put(cursor3, "OP2", input2)
;
map.put("criteria", input3) ;
//Run the search
IData result = invoke(NSName.create("pub.cacheimpl:search"), idata);

pub.cache.admin:clearAllCaches
WmPublic. Deletes all of the elements from all caches contained in the specied cache
manager.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cachePrex

String Optional. Prex of the name of the caches from which

to delete elements. If you do not specify a prex, the service
deletes elements from all caches in the cache manager.
Note: If pub.cache.admin:clearAllCaches does not nd any caches with
the specied prex, the service does not clear any caches.

Output Parameters
status

String The status indicating either Error or Success.

message

String The status message.

Usage Notes
Note: Only users with administrator privileges can execute this service.
Important: The elements you delete from the caches are deleted permanently. You cannot
undo this action.
If pub.cache.admin:clearAllCaches does not nd any caches with the specied prex, the
service does not clear any caches, but returns Success for status .
You cannot clear caches managed by system cache managers.
If you have any existing locks on any of the elements in the cache, the
pub.cache.admin:clearAllCaches service waits indenitely until all locks are released.
Integration Server returns a status of Error in the following cases:

webMethods Integration Server Built-In Services Reference Version 9.6

66

Odd Header
Cache Folder

If the cache is managed by a system cache manager.

If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager.
If a cache operation fails.

pub.cache.admin:clearCache
WmPublic. Deletes all elements from the specied cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which to delete the elements.

This parameter is case sensitive.

Output Parameters
status

String The status indicating either Error or Success.

message

String The status message.

Usage Notes
Note: Only users with administrator privileges can execute this service.
Important: The elements you delete from the cache are deleted permanently. You cannot
undo this action.
You cannot clear caches managed by system cache managers.
If you have any existing locks on any of the elements in the cache, the
pub.cache.admin:clearCache service waits indenitely until all locks are released.
Integration Server returns a status of Error in the following cases:
If the cache is managed by a system cache manager.
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

webMethods Integration Server Built-In Services Reference Version 9.6

67

Even Header
Cache Folder

pub.cache.admin:disableCache
WmPublic. Disables a cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache to disable. This parameter is case

sensitive.

Output Parameters
status

String The status indicating either Error or Success.

message

String The status message.

Usage Notes
Note: Only users with administrator privileges can execute this service.
When you disable a cache, the cached elements are unavailable for cache operations but
still present in the cache. Use the pub.cache.admin:enableCache service to make the disabled
cached elements available again.
You cannot disable caches managed by system cache managers.
After the pub.cache.admin:disableCache service disables a cache, other services cannot add,
modify, delete, or retrieve its contents. For example, calls to the pub.cache:get service will
return null.
The disabled state of a cache lasts only for the lifetime of its cache manager. When the
cache manager is restarted, either by restarting Integration Server or clicking the reload
icon on the Settings > Caching page in Integration Server Administrator, the cache is
enabled.
When you disable a cache, Integration Server:
Discards operations such as pub.cache:get, pub.cache:remove, and pub.cache.atomic:replace
calls on the cache.
Returns a null for pub.cache:get calls on the cache.
Integration Server returns a status of Error in the following cases:
If the cache is managed by a system cache manager.

webMethods Integration Server Built-In Services Reference Version 9.6

68

Odd Header
Cache Folder

If you do not specify all required input parameters.

If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.admin:enableCache
WmPublic. Enables a cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache to enable. This parameter is case

sensitive.

Output Parameters
status

String The status indicating either Error or Success.

message

String The status message.

Usage Notes
Note: Only users with administrator privileges can execute this service.
You cannot enable caches managed by system cache managers.
When you disable a cache, the cached elements are unavailable but still present in the
cache. Use pub.cache.admin:enableCache to make the cached elements available again.
Integration Server returns a status of Error in the following cases:
If the cache is managed by a system cache manager.
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.admin:evictExpiredElements
WmPublic. Deletes all of the expired elements from a cache.

webMethods Integration Server Built-In Services Reference Version 9.6

69

Even Header
Cache Folder

Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which you want to delete the
expired elements. This parameter is case sensitive.

Output Parameters
status

String The status indicating either Error or Success.

message

String The status message.

Usage Notes
Note: Only users with administrator privileges can execute this service.
Important: The elements you delete from the cache are deleted permanently. You cannot
undo this action.
The pub.cache.admin:evictExpiredElements service can take longer to delete expired elements
depending on the number of elements contained in the cache. If the cache contains a
large number of elements, pub.cache.admin:evictExpiredElements might take longer to process
the request than when the cache contains fewer elements.
Integration Server returns a status of Error in the following cases:
If the cache is managed by a system cache manager.
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.admin:isCacheDisabled
WmPublic. Checks whether the cache is disabled.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

webMethods Integration Server Built-In Services Reference Version 9.6

70

Odd Header
Cache Folder

cacheName

String Name of the cache for which you want to check the
status (whether it is disabled or enabled). This parameter is
case sensitive.

Output Parameters
isDisabled

String Indicates whether the cache is disabled. A value of:

true indicates that the cache is disabled.
false indicates that the cache is enabled.

status

String Conditional. The status indicating Error. The service

returns Error for status only if the service fails when checking
whether the cache is disabled.

message

String Conditional. The status message of the error. The service

returns message with status only if an error occurs when
checking whether the cache is disabled.

Usage Notes
Note: Only users with administrator privileges can execute this service.
pub.cache.admin:isCacheDisabled returns Error for status and an accompanying message in
the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.atomic:putIfAbsent
WmPublic. Adds an element to the cache if the cache does not contain an element with
the specied key.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache to which to add the element. This

parameter is case sensitive.

webMethods Integration Server Built-In Services Reference Version 9.6

71

Even Header
Cache Folder

key

Object Key of the element.

value

Object Value to add to the element.

Output Parameters
keyExists

String Indicates whether an element with the specied key

exists in the cache.
true indicates that an element with the key already exists in

the cache.

false indicates that an element with the key does not exist in

the cache.
oldValue

Object Conditional. Value of the element that already exists in

the cache. Returned only if keyExists is true.

Usage Notes
The pub.cache.atomic:putIfAbsent service adds the specied value to the cache only if the
specied key does not already exist in the cache. If the specied key already exists in the
cache, pub.cache.atomic:putIfAbsent returns true for keyExists and the value of the cached
element for oldValue .
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.atomic:remove
WmPublic. Removes the cached element associated with the specied key and value.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache from which to remove the element.

This parameter is case sensitive.

key

Object Key of the element to remove.

webMethods Integration Server Built-In Services Reference Version 9.6

72

Odd Header
Cache Folder

value

Object Value of the element to remove.

Output Parameters
removed

String Indicates whether the service removed the element.

true indicates that the element was removed from the cache.
false indicates that the element was not removed from the
cache. The service returns false if the specied key and

value do not exist in the cache.

Usage Notes

Integration Server issues a ServiceException in the following cases:

If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.atomic:replace
WmPublic. Replaces the cached element value with the supplied value.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the value you want to
replace. This parameter is case sensitive.

key

Object Key of the cache element whose value you want to

replace.

oldValue

Object Value of the cached element.

newValue

Object Value with which to replace the value of the cached

element.

webMethods Integration Server Built-In Services Reference Version 9.6

73

Even Header
Cache Folder

Output Parameters
replaced

String Indicates whether the service replaced oldValue with

newValue in the cache.
true indicates that the value was replaced in the cache.
false indicates that the value was not replaced in the cache.

Usage Notes
The pub.cache.atomic:replace service replaces an element in the cache only if an element
with the values of the specied key and oldValue parameters already exist in the cache. If
an element exist in the cache with the specied key and oldValue , pub.cache.atomic:replace
replaces the cached element with the specied key and newValue .
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.atomic:replaceIfKeyExists
WmPublic. Replaces the cached element if an element for the specied key exists in a
cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the key. This parameter
is case sensitive.

key

Object Key of the element whose value you want to replace.

value

Object Value with which to replace the value of the cached

element.

webMethods Integration Server Built-In Services Reference Version 9.6

74

Odd Header
Cache Folder

Output Parameters
keyExists

String Indicates whether the element with the passed key exists
in the cache.
true indicates that the element with the key already exists in

the cache.

false indicates that the element with the key does not exist

in the cache.
oldValue

Object Conditional. Value of the element the service replaced

with value . Returned only if keyExists is true.

Usage Notes
The pub.cache.atomic:replaceIfKeyExists service replaces an element in the cache only if the
specied key already exists in the cache. If an element with the specied key exists,
pub.cache.atomic:replaceIfKeyExists replaces value of the cached element with the one
specied in value .
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.bulk:isClusterBulkLoadEnabled
WmPublic. Checks whether the cache on at least one Integration Server node in the
Terracoa Server Array cluster is enabled for bulk loading.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache to check for bulk loading. This

parameter is case sensitive.

webMethods Integration Server Built-In Services Reference Version 9.6

75

Even Header
Cache Folder

Output Parameters
enabled

String Indicates whether the cache on at least one Integration

Server node of the Terracoa Server Array cluster is in bulkload mode.
true indicates that at least one node is in bulk-load mode.
false indicates that the node is not in bulk-load mode.

Usage Notes
The pub.cache.bulk:isClusterBulkLoadEnabled service applies only to distributed caches. If you
run pub.cache.bulk:isClusterBulkLoadEnabled on a local cache, the service returns false for
enabled .
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.bulk:isNodeBulkLoadEnabled
WmPublic. Checks whether the cache of the current Integration Server node in the
Terracoa Server Array cluster is bulk-load enabled.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the distributed cache to check for bulk loading.

This parameter is case sensitive.

Output Parameters
enabled

String Indicates whether the cache is enabled for bulk loading.

true indicates that the Integration Server node calling the
service is the same one that enabled bulk-loading.
false indicates one of the following:

webMethods Integration Server Built-In Services Reference Version 9.6

76

Odd Header
Cache Folder

The Integration Server node calling the service was not

the same node that enabled bulk loading.
The specied cache is a local cache.
Usage Notes
The pub.cache.bulk:isNodeBulkLoadEnabled service applies only to distributed caches.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.bulk:setNodeBulkLoadEnabled
WmPublic. Enables or disables bulk loading mode in the current Integration Server node
for the cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache on which to enable or disable bulk

loading. This parameter is case sensitive.

bulkMode

String Indicates whether to enable the bulk-load mode for the

cache. Set to:
true to enable the bulk-load mode. This is the default.
false to disable the bulk-load mode.

Output Parameters
None.
Usage Notes
The pub.cache.bulk:setNodeBulkLoadEnabled service applies only to distributed caches.
The pub.cache.bulk:setNodeBulkLoadEnabled service does nothing if you:
Try to enable bulk loading (bulkMode set to true) when the node is already in bulkload mode.

webMethods Integration Server Built-In Services Reference Version 9.6

77

Even Header
Cache Folder

Try to disable bulk loading (bulkMode set to false) when the node is not already in
bulk-load mode.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.bulk:waitUntilClusterBulkLoadComplete
WmPublic. Indicates whether Integration Server delays execution of the next step in
a ow service until all of the Integration Server nodes in the Terracoa Server Array
cluster disable bulk loading for the cache.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache on which to hold processing. This

parameter is case sensitive.

Output Parameters
None.
Usage Notes
The pub.cache.bulk:waitUntilClusterBulkLoadComplete service applies only to distributed caches.
If none of the nodes are bulk-load enabled, Integration Server immediately executes the
next step in the ow service without waiting.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If a cache operation fails.

pub.cache.lock:acquireLock
WmPublic. Acquires a lock on the cached element that contains the specied key.

webMethods Integration Server Built-In Services Reference Version 9.6

78

Odd Header
Cache Folder

Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the element to lock. This
parameter is case sensitive.

key

Object Key of the cached element to lock.

lockType

String Optional. Type of lock you want to place on the cached

element.

lockWaitTime

Key

Description

read

Places a read lock on the key. This is the

default.

write

Places a write lock on the key.

String Optional. Amount of time in milliseconds to wait to

acquire a lock before timing out.
Key

Description

Any integer less

than 0

The service waits indenitely until it

acquires a lock.

The service fails if it is unable to acquire

the lock immediately. This is the default.

Any integer
greater than 0

The service fails if it is unable to acquire

the lock within the specied time.

Output Parameters
None.
Usage Notes
If the pub.cache.lock:acquireLock service acquires a lock, the element remains locked until
released with the pub.cache.lock:releaseLock service.
You must acquire and release a lock in the same thread in which pub.cache.lock:acquireLock
is executing. Failing to do so could cause the key to remain locked indenitely.

webMethods Integration Server Built-In Services Reference Version 9.6

79

Even Header
Cache Folder

When using the debug ow service to step through a ow service, depending on

your breakpoint seings Designer might use a new thread for each step. You cannot
release a lock acquired in a previous step of the same ow if break points are triggered
on Designer or if you are stepping through a ow service. To avoid orphaned locks,
disable invocations of pub.cache.lock:acquireLock and pub.cache.lock:releaseLock before
stepping through the ow service or make sure that pub.cache.lock:acquireLock and
pub.cache.lock:releaseLock services are called between the boundaries of two breakpoints.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
Whether or not a cached element needs to be locked depends on the application that
is using the element. For example, if an application retrieves and holds an element
for a time and needs to prevent another client from changing the element during
this time, the application should acquire a lock on the element. However, if the
application does not hold the element, a lock might not be required.
If Integration Server cannot nd the specied cache manager or cache.
If pub.cache.lock:acquireLock is unable to acquire a lock.
If the specied lockWaitTime is not a valid integer.
If a cache operation fails.

pub.cache.lock:isLockedByCurrentThread
WmPublic. Checks whether the current thread is holding a lock on the cached element
for the specied key.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the key. This parameter
is case sensitive.

key

Object Key for which you want to check locks.

lockType

String Optional. Type of lock for which to check the cached

element.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

80

Odd Header
Cache Folder

read

The service checks whether the read lock

is held for the current thread. This is the
default.

write

The service checks whether the write lock

is held for the current thread.

Output Parameters
locked

String Indicates whether the cached element is locked by the

current thread.
true indicates that the element is locked.
false indicates that the element is not locked.

Note: If the specied cache is a local cache and the specied

lockType is read , the service always returns false.
Usage Notes
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.

pub.cache.lock:releaseLock
WmPublic. Releases a lock on the element for the specied key.
Input Parameters
cacheManagerName

String Name of the cache manager that manages the cache. This
parameter is case sensitive.

cacheName

String Name of the cache that contains the key. This parameter
is case sensitive.

key

Object Key of the cached element to unlock.

lockType

String Optional. Type of lock you want to release from the

cached element.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

81

Even Header
Cache Folder

read

Releases a read lock. This is the default.

write

Releases a write lock.

Output Parameters
None.
Usage Notes
You must call pub.cache.lock:releaseLock from the same thread from which you call
pub.cache.lock:acquireLock. Failing to do so could cause the key to remain locked
indenitely.
Integration Server issues a ServiceException in the following cases:
If you do not specify all required input parameters.
If Integration Server cannot nd the specied cache manager or cache.
If you try to release a read lock on a cached element for which a write lock is set, or
release a write lock on a cached element for which a read lock is set.

webMethods Integration Server Built-In Services Reference Version 9.6

82

Odd Header
Client Folder

3 Client Folder
Summary of Elements in this Folder ...........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

84

83

Even Header
Client Folder

You use the elements in the client folder to formulate and submit requests to HTTP, FTP,
SFTP, e-mail, and LDAP servers.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.client:ftp

WmPublic. Performs a series of FTP actions.

pub.client.ftp:append

WmPublic. Appends data to a remote le.

pub.client.ftp:cd

WmPublic. Changes the working directory on the FTP

server. (This service corresponds to the standard FTP
command cd dirpath.)

pub.client.ftp:cdls

WmPublic. Changes the working directory on the

FTP server and retrieves a list of le names. (This
service corresponds to the standard FTP commands
cd dirpath and ls namePattern.)

pub.client.ftp:delete

WmPublic. Deletes a le in the current working

directory on an FTP server. (This service corresponds
to the standard FTP command delete somefile.)

pub.client.ftp:dir

WmPublic. Retrieves the le list during an FTP

session. (This service corresponds to the standard FTP
command dir namepattern.)

pub.client.ftp:get

WmPublic. Retrieves a le from a remote FTP server.

(This service corresponds to the standard FTP
command get.)

pub.client.ftp:getCompletedNotification

WmPublic. A publishable document type that

represents the document published to notify parties
that an FTP get command has completed.

pub.client.ftp:login

WmPublic. Connects to a remote FTP server and logs

in with a specied user name and password.

pub.client.ftp:logout

WmPublic. Logs o of the FTP server and ends the

current FTP session.

webMethods Integration Server Built-In Services Reference Version 9.6

84

Odd Header
Client Folder

Element

Package and Description

pub.client.ftp:ls

WmPublic. Retrieves the le list during an FTP

session. (This service corresponds to the standard FTP
command ls namepattern.)

pub.client.ftp:mdelete

WmPublic. Deletes multiple les in the current

working directory on an FTP server. (This service
corresponds to the standard FTP command mdelete
pattern.)

pub.client.ftp:mget

WmPublic. Transfers multiple les from the remote

FTP server. (This service corresponds to the standard
FTP command mget.)

pub.client.ftp:mput

WmPublic. Transfers multiple les to a remote FTP

server. (This service corresponds to the standard FTP
command input.)

pub.client.ftp:put

WmPublic. Transfers a le to a remote FTP server.

(This service corresponds to the standard FTP
command put.)

pub.client.ftp:putCompletedNotification

WmPublic. A publishable document type that

represents the document published to notify parties
that an FTP put command has completed.

pub.client.ftp:quote

WmPublic. Executes a given FTP command.

pub.client.ftp:rename

WmPublic. Renames a le on a remote FTP server.

(This service corresponds to the standard FTP
command rename.)

pub.client.ftp:sessioninfo

WmPublic. Returns session information for all of the

FTP servers that users are currently logged into.

pub.client:http

WmPublic. Issues an HTTP request that you specify

and returns the HTTP response.

pub.client.ldap:add

WmPublic. Inserts a new entry into the directory.

pub.client.ldap:bind

WmPublic. Performs an LDAP bind operation that

associates the connection with the specied principal.

webMethods Integration Server Built-In Services Reference Version 9.6

85

Even Header
Client Folder

Element

Package and Description

pub.client.ldap:cancelNotification

WmPublic. Cancels a previously created notication

request.

pub.client.ldap:compare

WmPublic. Compares the value of an aribute in the

LDAP directory with a value specied by the service.

pub.client.ldap:delete

WmPublic. Removes an entry from the directory.

pub.client.ldap:modify

WmPublic. Performs an LDAP modify operation

that allows you to specify a list of aributes with
corresponding lists of values to add to, replace, or
remove from the directory entry.

pub.client.ldap:registerNotification

WmPublic. Creates a notication (or "persistent

search") that causes Integration Server to listen for
LDAP events. When the notication gets an event, the
specied service is called.

pub.client.ldap:rename

WmPublic. Performs an LDAP rename (move)

operation allowing you to rename an entry.

pub.client.ldap:search

WmPublic. Performs an LDAP search operation with

the specied parameters and returns the results of the
search.

pub.client.oauth:executeRequest

WmPublic. Allow clients to access protected resources

using an OAuth token.

pub.client.sftp:cd

WmPublic. Changes the working directory on the

remote SFTP server.

pub.client.sftp:chgrp

WmPublic. Changes the group ownership of one or

more remote les.

pub.client.sftp:chmod

WmPublic. Changes permissions of one or more

remote les.

pub.client.sftp:chown

WmPublic. Changes the user of one or more remote

les.

pub.client.sftp:get

WmPublic. Retrieves a le from a remote SFTP server

and saves it on the local machine.

webMethods Integration Server Built-In Services Reference Version 9.6

86

Odd Header
Client Folder

Element

Package and Description

pub.client.sftp:login

WmPublic. Connects to a remote SFTP server and

logs in with the specied SFTP user alias.

pub.client.sftp:logout

WmPublic. Logs o the user from the SFTP server

and ends the current SFTP session.

pub.client.sftp:ls

WmPublic. Retrieves the remote directory listing of

the specied path or current remote directory if path
is not specied.

pub.client.sftp:mkdir

WmPublic. Creates a new remote directory.

pub.client.sftp:put

WmPublic. Transfers a le to a remote SFTP server.

pub.client.sftp:pwd

WmPublic. Displays the remote working directory on

the SFTP server.

pub.client.sftp:rename

WmPublic. Renames a le or directory on a remote

SFTP server.

pub.client.sftp:rm

WmPublic. Deletes one or more remote les on the

SFTP server.

pub.client.sftp:rmdir

WmPublic. Deletes one or more remote directories on

the SFTP server.

pub.client.sftp:symlink

WmPublic. Creates a symbolic link between the old

path and the new path of a le.

pub.client:smtp

WmPublic. Sends a MIME-type e-mail message.

pub.client:soapClient

WmPublic. Creates and sends SOAP 1.1 and

SOAP 1.2 messages over HTTP, HTTPS, or JMS
transports for any style/use combination supported
by Integration Server.

pub.client:soapHTTP

WmPublic. Deprecated - Submits a SOAP message to a

server via HTTP or HTTPS.

pub.client:soapRPC

WmPublic. Deprecated - Submits a SOAP remote

procedure call via HTTP or HTTPS.

webMethods Integration Server Built-In Services Reference Version 9.6

87

Even Header
Client Folder

pub.client:ftp
WmPublic. Performs a series of FTP actions.
This service executes the following sequence:
1. Logs on to an FTP server.
2. Changes to a specied working directory.
3. Performs one of the following FTP commands: ls, put, or get.
4. Logs o the FTP server.
Input Parameters
serverhost

String Name or IP address of the FTP server (for example,

ftp.netscape.com).

serverport

String Port number of the FTP server (for example, 4566).

username

String Valid FTP user of the remote FTP server (for example,
anonymous).

password

String Optional. Valid password of the FTP user.

command

String One of the following FTP commands: ls, put, or get.

dirpath

String Working directory of the FTP server (for example, /tmp/pub).

If the directory does not exist, the server throws an exception.

transfermode

String One of two FTP le transfer modes: ascii or binary. The

default is ascii.

transfertype

String One of two FTP data transfer types: passive or active. The
default is active.

localle

String When command is set to put, this parameter species the

name of the local le you want to transfer. (If content is specied,
this eld is ignored.)
When command is set to get, this parameter species the name of
the local le in which you want the retrieved content saved.

webMethods Integration Server Built-In Services Reference Version 9.6

88

Odd Header
Client Folder

remotele

String When command is set to put, this parameter species the

name of the remote le in which you want the save the data you
are sending.
When command is set to get, this parameter species the name of
the remote le that you want to retrieve.

content

java.io.InputStream, byte[ ], or String Data to be transferred when

command is set to put.

encoding

String Optional. Character set in which the document is

encoded. Specify an IANA-registered character set (for example,
ISO-8859-1).
This information is required to correctly convert the String object to
bytes when performing a get. If parameter is null, the default JVM
encoding is used.

serverencoding

String Optional. Species the encoding this service uses to convert

the incoming FTP command string to encoded bytes that are
supported by IANA and the FTP server. If the parameter is
null, the service uses the 'UTF-8' character set to encode the FTP
command String to bytes.

timeout

String Time (measured in seconds) this service waits for the FTP
server response on the command channel before timing out and
aborting the request. Default is to wait forever.

putunique

String Optional. Indicates whether to send a STOR or a STOU (Store

as Unique File) command to the remote FTP server. Set to:
true to send a STOU (Store as Unique File) command.
false to send a STOR command. This is the default.

secure

Document Indicates whether the FTP session is with a secure FTP

server.
Key

Description

auth

String The kind of authentication mechanism

to use: None, SSL, TLS, or TLS-P.
None species that the FTP session is with a
non-secure FTP server. This is the default.
If the value of auth is None, the securedata
variable is ignored.

webMethods Integration Server Built-In Services Reference Version 9.6

89

Even Header
Client Folder

TLS-P is a shortcut that is equivalent to the

sequence AUTH TLS, PBSZ 0, and PROT P.
If the value of auth is TLS-P, the securedata

variable is ignored.
securedata

String Use the value false for a client

sending PROT C (Data Channel Protection
Level Clear).
Use the value true for a client sending
PROT P (Data Channel Protection Level
Private).
Note: If you do not set a value, the default is
false.

cleanlinefeeds

String Optional. Indicates whether the service should retain or

remove carriage return characters at the end of each line of text. Set
to:
true to remove carriage returns. This is the default.
false to retain carriage returns.

newSession

String Optional. Flag indicating whether a a new FTP session will

be created for this FTP operation. Set to:
yes to create a new session for this FTP operation.
no to use the current session, if one is available, for this FTP

operation. This is the default.

clientTimeout

String Optional. Species the idle time-out, measured in seconds,

for this FTP session. If clientTimeout is set to 0 (zero), the session
will never time out. The default is 600 seconds (10 minutes).

proxyAlias

String Optional. Name of the proxy server alias for the proxy server
to which Integration Server routes the FTP request.
If you do not specify a proxyAlias , Integration Server routes the
FTP request through the proxy server specied in the default
FTP proxy alias. If there is no default FTP proxy alias, the action
taken by Integration Server depends on the value specied for the
wa.net.proxy.useNonDefaultProxies parameter.
If the wa.net.proxy.useNonDefaultProxies parameter is set
to true, Integration Server routes the FTP request through the
proxy server in any congured FTP proxy alias. If the Integration
Server does not have any dened FTP proxy aliases, Integration
Server sends the FTP request directly to the FTP server or

webMethods Integration Server Built-In Services Reference Version 9.6

90

Odd Header
Client Folder

throws an exception depending on the seings specied for the

wa.net.proxy.fallbackToDirectConnection parameter.
If the wa.server.proxy.useNonDefaultProxies parameter is set
to false, Integration Server sends the request to the remote server
using a direct connection.
For more information about proxy server usage, refer to
webMethods Integration Server Administrators Guide.
Output Parameters
command

String FTP command that was executed (ls, get, or put).

dirlist

String List File names returned by the ls command.

localle

String Name of the local le used for a get or put operation.

remotele

String Name of the remote le used for a get or put operation.

content

byte[ ] If localle was not specied, this parameter contains the

Content object sent to the remote server (if a put command was
executed) or received from the remote server (if a get command was
executed).

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log message.

Usage Notes
If you set the auth variable in the secure parameter to SSL, TLS, or TLS-P, pub.client.ftp
automatically sends the following sequence of FTP commands prior to sending the
USER command:
AUTH <SSL | TLS | TLS-P>

PBSZ 0

PROT <P | C>

The client FTP services will not negotiate for less security than you have specied with
the auth parameter. However, if you set the auth variable to None, the client FTP services
can operate (in a non-secure mode) with any FTP server.
The FTP services will always connect to a secure FTP server using a non-secure (SSL)
socket. After geing a valid reply from the AUTH command, the FTP services will
convert the connected socket to an SSL socket and initiate SSL handshaking.

webMethods Integration Server Built-In Services Reference Version 9.6

91

Even Header
Client Folder

pub.client.ftp:append
WmPublic. Appends data to a remote le.
If the remote le does not exist, the service creates the le.
Input Parameters
String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

sessionkey

String FTP le transfer mode (ascii or binary). The default is

transfermode

ascii.

content

java.io.InputStream, byte[ ], or String Data to be transferred to the

remote le.

localle

String Optional. Name of the local le to append to the remote le.

Used only when content is not specied.

remotele

String Name of the remote le to which to append the data specied

in content or localle .

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:cd
WmPublic. Changes the working directory on the FTP server. (This service corresponds
to the standard FTP command cd dirpath.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

webMethods Integration Server Built-In Services Reference Version 9.6

92

Odd Header
Client Folder

dirpath

String Directory to which you want to switch on the FTP server. For
example: pub

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:cdls
WmPublic. Changes the working directory on the FTP server and retrieves a list of le
names. (This service corresponds to the standard FTP commands cd dirpath and ls
namePattern.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

dirpath

String Directory to which you want to switch on the FTP server

(for example, pub).

lenamepaern

String Optional. Paern that species the le names to list (for

example, *.txt).

orderby

String Optional. The order of the returned le list. Set to:

none to send an NLST command to the remote FTP server. This

is the default.

timestamp to return the list in order of the timestamp. Sends an

NLST -t command to the remote FTP server.

Note: The -t command is not part of the RFC959 standard.

Some FTP servers may not support this command. Servers
that support this command may return the results in either
ascending or descending order of creation time.

webMethods Integration Server Built-In Services Reference Version 9.6

93

Even Header
Client Folder

Output Parameters
dirlist

String List List of le names matching lenamepaern .

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:delete
WmPublic. Deletes a le in the current working directory on an FTP server. (This service
corresponds to the standard FTP command delete somefile.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

remotele

String Name of the le to be deleted from the current working

directory. For example: text.txt
If you specify paern-matching characters in remotele , all les
matching the paern will be deleted.

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:dir
WmPublic. Retrieves the le list during an FTP session. (This service corresponds to the
standard FTP command dir namepattern.)

webMethods Integration Server Built-In Services Reference Version 9.6

94

Odd Header
Client Folder

Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

lenamepaern

String Optional. Paern that species the names of the les to

include in the list (for example, *.txt).

Output Parameters
dirlist

String List Directory listing of the les matching lenamepaern

including the le names and timestamps.

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:get
WmPublic. Retrieves a le from a remote FTP server. (This service corresponds to the
standard FTP command get.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

transfermode

String FTP le transfer mode (ascii or binary). The default is

ascii.

localle

String Optional. Name of a local le where the retrieved le is to

be saved.

remotele

String Name of the remote le.

encoding

String Optional. Character set in which the le is encoded. This

variable is required to convert the le to bytes correctly. Specify
an IANA-registered character set (for example: ISO-8859-1).

webMethods Integration Server Built-In Services Reference Version 9.6

95

Even Header
Client Folder

If this variable is null, the encoding currently set for the FTP
session is used. If encoding was never set for this FTP session, the
default JVM encoding is used.
largelethreshold

String Optional. Denes the size (in bytes) of a "large" le. For
more information, see the Usage Notes.
If you...

Then...

Set to 0

All les will be considered large les. This

means:
The output parameter islargele will
always be true.
The le content will be returned in the
output parameter contentstream (as a
java.io.InputStream object).
The output parameter content will be null.

Set to any value

greater than 0

Any le larger than the value you specify

will be considered large. This means:
The output parameter islargele will be
true.
The le content will be returned in the
output parameter contentstream (as a
java.io.InputStream object).
The output parameter content will be null.

Leave blank

No le is considered large. This means:

The output parameter islargele will
always be false.
The le content will be returned in the
output parameter content ().
The output parameter contentstream will
be null.

cleanlinefeeds

String Optional. Indicates whether the service should retain or

remove carriage return characters at the end of each line of text.
Set to:
true to remove carriage returns.
false to retain carriage returns. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

96

Odd Header
Client Folder

Output Parameters
content

byte[ ] Data retrieved from the remote le.

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

islargele

String Indicates whether the le is considered to be large (as

specied by the input parameter largelethreshold ). A value of:
true indicates that the le is larger than the value of

largethreshold .

false indicates that the le is not larger than the value of

largethreshold (or largethreshold is blank).

contentstream

Object An java.io.InputStream object.

Usage Notes
The largelethreshold parameter improves the ability of pub.client.ftp:get to retrieve
larger les. If a retrieved le is larger than the size specied in the largelethreshold
parameter, and the localle parameter is empty (which means the retrieved le is
retrieved to memory, not to a le on disk), the Integration Server streams the large le
to a temporary le. While this will improve the scalability of pub.client.ftp:get, it will
also reduce the throughput of the operation because the retrieved le will be wrien to a
temporary le.
Tip: Due to the impact to the throughput of pub.client.ftp:get when streaming is enabled,
you should set the value for largelethreshold to a suciently large value so that it causes
only minimal degradation to throughput and yet allows the service to retrieve large les
without encountering an OutOfMemory exception.
See Also
pub.io:close

pub.client.ftp:getCompletedNotification
WmPublic. A publishable document type that represents the document published to
notify parties that an FTP get command has completed on Integration Server which is
acting as the FTP server.

webMethods Integration Server Built-In Services Reference Version 9.6

97

Even Header
Client Folder

When a user completes an FTP get command in his or her own user directory (that is,
when the RETR command is completed on the server side but the server has not yet
acknowledged the client with return code 226), an event is red to notify interested
parties by publishing a document. EDI packages that subscribe to this document will
retrieve the le from the server.
Parameters
username

String The login user name through the FTP Listener.

lename

String The absolute path name of the le.

_env

Document Optional. A document reference to pub.publish:envelope which

denes the structure and contents of the envelope of a published
document.

Usage Notes
Integration Server publishes an instance document of pub.client.ftp:getCompletedNotification
when an FTP client has completed an FTP get command on Integration Server through
an FTP/S port. Because the retrieved le is located on the Integration Server le system,
only subscribers located on the same Integration Server would have access to the le.
Consequently the pub.client.ftp:getCompletedNotification publishable document type is set
to publish locally only. When Integration Server publishes an instance document for
pub.client.ftp:getCompletedNotification, only subscribers located on the same Integration Server
receive the document. Software AG does not recommend synchronizing the publishable
document type with the messaging provider.

pub.client.ftp:login
WmPublic. Connects to a remote FTP server and logs in with a specied user name and
password.
You must use this service to initiate an FTP session before using most other services in
pub.client.ftp.
Input Parameters
serverhost

String Name or IP address of the FTP server (for example,

ftp.netscape.com).

serverport

String Port number on which the FTP server listens for requests (for
example, 4566).
The default is 21.

webMethods Integration Server Built-In Services Reference Version 9.6

98

Odd Header
Client Folder

dataport

String Optional. Listener port number of the data transfer channel

(for example, 3345).
If you do not specify dataport , the Integration Server will choose the
listener port number. This value is used only when the transfertype
value is active.

username

String Valid FTP user on the remote FTP server (for example,
anonymous).

password

String Optional. Valid password for the FTP user specied in

username (for example, someone@somewhere).

account

String Optional. The user name for an account on the FTP server.
Specify account if your FTP host requires account information. The
account is dened in the FTP protocol to further identify the user
that is identied by the username and password input variables.

transfertype

String Type of the FTP data transfer mode (passive or active). The
default is active.

encoding

String Optional. Default character set for encoding data transferred

during this session. Specify an IANA-registered character set (for
example, ISO-8859-1).
If you do not set encoding , the default JVM encoding is used.

serverencoding

String Optional. Species the encoding this service uses to convert

the incoming FTP command string to encoded bytes that are
supported by IANA and the FTP server. If the parameter is null, the
service uses the 'UTF-8' character set to encode the FTP command
String to bytes.

timeout

String Optional. Time (measured in seconds) to wait for a response

from the FTP server before timing out and terminating the request.
The default is to wait forever.

secure

Document Indicates whether the FTP session is with a secure FTP

server.
Key

Description

auth

String The kind of authentication

mechanism to use: None, SSL, TLS, or TLSP.

webMethods Integration Server Built-In Services Reference Version 9.6

99

Even Header
Client Folder

None species that the FTP session is with a

non-secure FTP server. This is the default.
If the value of auth is None, the securedata
variable is ignored.

TLS-P is a shortcut that is equivalent to the

sequence AUTH TLS, PBSZ 0, and PROT P.
If the value of auth is TLS-P, the securedata
variable is ignored.
securedata

String Use the value false for a client

sending PROT C (Data Channel Protection
Level Clear).
Use the value true for a client sending
PROT P (Data Channel Protection Level
Private).
Note: If you do not set a value, the default is
false.

newSession

String Optional. Flag indicating whether a a new FTP session will be

created for this FTP operation. Set to:
yes to create a new session for this FTP operation.
no to use the current session, if one is available, for this FTP

operation. This is the default.

clientTimeout

String Optional. Species the idle time-out, measured in seconds, for

this FTP session. If clientTimeout is set to 0 (zero), the session will
never time out. The default is 600 seconds (10 minutes).

proxyAlias

String Optional. Name of the proxy alias for the proxy server
through which Integration Server routes the FTP request.
If you do not specify a proxyAlias , Integration Server routes the
FTP request through the proxy server specied in the default
FTP proxy alias. If there is no default FTP proxy alias, the action
taken by Integration Server depends on the value specied for the
wa.net.proxy.useNonDefaultProxies parameter.
If the wa.net.proxy.useNonDefaultProxies parameter is set
to true, Integration Server routes the FTP request through the
proxy server in any congured FTP proxy alias. If the Integration
Server does not have any dened FTP proxy aliases, Integration
Server sends the FTP request directly to the FTP server or
throws an exception depending on the seings specied for the
wa.net.proxy.fallbackToDirectConnection parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

100

Odd Header
Client Folder

If the wa.server.proxy.useNonDefaultProxies parameter is set

to false, Integration Server sends the request to the remote server
using a direct connection.
For more information about proxy server usage, refer to webMethods
Integration Server Administrators Guide.
Output Parameters
sessionkey

String Unique key for the current FTP session. This session key must
be provided to execute most other services in pub.client.ftp.

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

Usage Notes
If you set the auth variable in the secure parameter to SSL, TLS, or TLS-P,
pub.client.ftp:login automatically sends the following sequence of FTP commands prior
to sending the USER command:
AUTH <SSL | TLS | TLS-P>

PBSZ 0

PROT <P | C>

The client FTP services will not negotiate for less security than you have specied with
the auth parameter. However, if you set the auth variable to None, the client FTP services
can operate (in a non-secure mode) with any FTP server.
The FTP services will always connect to a secure FTP server using a non-secure (SSL)
socket. After geing a valid reply from the AUTH command, the FTP services will
convert the connected socket to an SSL socket and initiate SSL handshaking.

pub.client.ftp:logout
WmPublic. Logs o of the FTP server and ends the current FTP session.
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

webMethods Integration Server Built-In Services Reference Version 9.6

101

Even Header
Client Folder

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:ls
WmPublic. Retrieves the le list during an FTP session. (This service corresponds to the
standard FTP command ls namepattern.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

lenamepaern

String Optional. Paern that species the names of the les to

include in the list (for example, *.txt).

orderby

String Optional. The order of the returned le list.

Value of
orderby

Description

none

Default. Sends an NLST command to the

remote FTP server.

timestamp

Returns the list in order of the timestamp.

Sends an NLST -t command to the remote FTP
server.
Note: The -t command is not part of the RFC959
standard. Some FTP servers may not support this
command. Servers that support this command
may return the results in either ascending or
descending order of creation time.

webMethods Integration Server Built-In Services Reference Version 9.6

102

Odd Header
Client Folder

Output Parameters
dirlist

String List List of le names matching lenamepaern .

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

Usage Note
During an FTP session, this service uses the character set specied in the encoding
parameter of the pub.client.ftp:login service. If the le list this service retrieves includes
characters from other languages, set the encoding parameter appropriately. For example,
set encoding to SJIS for le names containing Japanese characters. If you do not set
encoding in pub.client.ftp:login, the default JVM encoding is used.

pub.client.ftp:mdelete
WmPublic. Deletes multiple les in the current working directory on an FTP server.
(This service corresponds to the standard FTP command mdelete pattern.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

lenamepaern

String Paern that species the names of the les to be deleted from
the current working directory (for example, *.txt).
Important: If you do not specify a value for lenamepaern , all les in
the working directory are deleted.

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

webMethods Integration Server Built-In Services Reference Version 9.6

103

Even Header
Client Folder

pub.client.ftp:mget
WmPublic. Transfers multiple les from the remote FTP server. (This service
corresponds to the standard FTP command mget.)
Input Parameters
sessionkey
transfermode

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.
String FTP le transfer mode (ascii or binary). The default is

ascii.

localdir

String Directory in the local le system where the retrieved les are
to be saved (for example, c:\temp\ftpfiles).

lenamepaern

String Paern that species the names of the les to be retrieved (for
example, *.txt).

encoding

String Optional. Character set in which the les are encoded. This
variable is required to convert the les to bytes correctly. Specify
an IANA-registered character set (for example, ISO-8859-1).
If you do not specify encoding , the encoding assigned to the FTP
session is used. If the encoding was not set for the FTP session, the
default JVM encoding is used.

Output Parameters
lenames

String List List of les retrieved from the remote FTP server.

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:mput
WmPublic. Transfers multiple les to a remote FTP server. (This service corresponds to
the standard FTP command input.)
webMethods Integration Server Built-In Services Reference Version 9.6

104

Odd Header
Client Folder

Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

transfermode

String FTP le transfer mode (ascii or binary). The default is

ascii.

localdir

String Local directory containing the les you want to transfer to

the remote FTP server (for example, c:\temp\ftpfiles).

lenamepaern

String Paern that species the names of the les to be transferred

(for example, *.txt).

putunique

String Optional. Indicates whether to send a STOR or a STOU (Store

as Unique File) command to the remote FTP server. Set to:
true to send a STOU (Store as Unique File) command.
false to send a STOR command. This is the default.

Output Parameters
lenames

String List List of les transferred to the remote FTP server.

returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

Usage Note
Some FTP servers, such as the Integration Server FTP Listener, do not support "puing"
a unique le. When using the pub.client.ftp:put or pub.client.ftp:mput service to put a unique
le to an FTP server that does not support puing a unique le, you will encounter an
error like this one:
com.wm.app.b2b.server.ServiceException: 500 'STOU': command not understood.

pub.client.ftp:put
WmPublic. Transfers a le to a remote FTP server. (This service corresponds to the
standard FTP command put.)

webMethods Integration Server Built-In Services Reference Version 9.6

105

Even Header
Client Folder

Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

transfermode

String FTP le transfer mode (ascii or binary). The default is

ascii.

content

java.io.InputStream, byte[ ], or String Data to be transferred to the

remote le.

localle

String Optional. Name of the local le to be appended to the remote

le. Used only if content is not specied.

remotele

String The name of the remote le.

putunique

String Optional. Indicates whether to send a STOR or a STOU

(Store as Unique File) command to the remote FTP server. Set to:
true to send a STOU (Store as Unique File) command.
false to send a STOR command. This is the default.

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

Usage Notes
Some FTP servers, such as the Integration Server FTP Listener, do not support
"puing" a unique le. When using the pub.client.ftp:put or pub.client.ftp:mput service to
put a unique le to an FTP server that does not support puing a unique le, you
will encounter an error like this one:
com.wm.app.b2b.server.ServiceException: 500 'STOU': command not understood.

When a client invokes this service to transport a le, the FTP listener determines
the content handler to use based on the le's extension. The content handler
converts the le content to the input values for the service to invoke. The
Integration Server_directory\instances\instance_name \lib\mime.types le contains
the mappings of le extension to content type.

webMethods Integration Server Built-In Services Reference Version 9.6

106

Odd Header
Client Folder

By default, if this service encounters a le that has no le extension, the default

content handler is used. To override this, you can congure any content
handler to handle les that have no le extension. To do this, add a line in the
Integration Server_directory\instances\instance_name \lib\mime.types le that
species the content type of the les with no extension, and the ftp_no_extension
key. For example, to allow a content handler to accept text/xml les that have no
extension, add this line to your mime.types le:
text/xml

ftp_no_extension

pub.client.ftp:putCompletedNotification
WmPublic. A publishable document type that represents the document published to
notify parties that an FTP put command has completed on Integration Server which is
acting as the FTP server.
When a user completes an FTP put command in his or her own user directory (that is,
when the STOR command is completed on the server side but the server has not yet
acknowledged the client with return code 226), an event is red to notify interested
parties by publishing a document. EDI packages that subscribe to this document will
retrieve the le from the server.
Parameters
username

String The login user name through the FTP Listener.

lename

String The absolute path name of the le.

_env

Document Optional. A document reference to pub.publish:envelope which

denes the structure and contents of the envelope of a published
document.

Usage Notes
Integration Server publishes an instance document of pub.client.ftp:putCompletedNotification
when an FTP client has completed an FTP put command on Integration Server through
an FTP/S port. Because the put le is located on the Integration Server le system,
only subscribers located on the same Integration Server would have access to the le.
Consequently the pub.client.ftp:putCompletedNotification publishable document type is set
to publish locally only. When Integration Server publishes an instance document for
pub.client.ftp:putCompletedNotification, only subscribers located on the same Integration Server
receive the document. Software AG does not recommend synchronizing the publishable
document type with a messaging provider.

webMethods Integration Server Built-In Services Reference Version 9.6

107

Even Header
Client Folder

pub.client.ftp:quote
WmPublic. Executes a given FTP command.
You can use this service to execute non-standard FTP commands.
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

string

String The command to be executed on the FTP server. This service

submits the command exactly as it is specied in string .

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:rename
WmPublic. Renames a le on a remote FTP server. (This service corresponds to the
standard FTP command rename.)
Input Parameters
sessionkey

String Unique key for the current FTP session. The sessionkey is
returned by the pub.client.ftp:login service.

oldname

String Fully qualied name of the le you want to rename (for

example, temp/oldname.txt).

newname

String New fully qualied name for the le (for example, temp/
newname.txt).

webMethods Integration Server Built-In Services Reference Version 9.6

108

Odd Header
Client Folder

Output Parameters
returncode

String Standard FTP protocol return code.

returnmsg

String Standard FTP protocol return message.

logmsg

String FTP log messages for the entire user session.

pub.client.ftp:sessioninfo
WmPublic. Returns session information for all of the FTP servers that users are currently
logged into.
Input Parameters
name

Not used. Reserved for future use.

Output Parameters
sessioninfo

Document List Information about the current FTP sessions. Each

document in sessioninfo represents a single session and contains the
following information:
Key

Description

serverhost

String Name or IP address of the FTP server.

serverport

String Port number on which the FTP server listens

for requests.

dataport

String Listener port of the data transfer channel

used by this session.

username

String User logged on to FTP server.

password

String Password for the FTP user specied in

username .

account

String Conditional. The user name for an account

on the FTP server. The account is dened in the
FTP protocol to further identify the user that is

webMethods Integration Server Built-In Services Reference Version 9.6

109

Even Header
Client Folder

identied by the username and password input

variables.
transfertype

String Data transfer mode (passive or active)

used by this session.

encoding

String Conditional. IANA character set used by this

session. If encoding is not returned, the encoding
was not explicitly set and the default JVM encoding
is in eect.

Usage Notes
When you start an FTP session with pub.client.ftp:login, you can set the optional dataport
parameter to specify the port number for data transfers. During the FTP session,
pub.client.ftp:sessionInfo returns the dataport parameter with the port number used for data
transfers.
If you do not set the dataport parameter in pub.client.ftp:login, the server uses a random port
number. During the FTP session, pub.client.ftp:sessionInfo will return a 0 for the dataport
parameter to indicate that the port number used for data transfers is random.

pub.client:http
WmPublic. Issues an HTTP request that you specify and returns the HTTP response.
Input Parameters
url

String URL of the resource that you want to access. For

example:
http://www.rubicon.com/orders/orders.html

Important: This string must begin with http: or https:.

method

String Species the HTTP method you want to use. Valid

values are:
delete
get
head
options
post
put
trace

webMethods Integration Server Built-In Services Reference Version 9.6

110

Odd Header
Client Folder

loadAs

String Optional. Form in which you want the hp service to

store the returned document. Set to:
bytes to return the body of the response as a byte[ ]. Use

this option if the body will be used as input to a service that

operates on whole HTML or XML documents (for example,
pub.xml:queryXMLNode). This is the default.
stream to return the body of the response as a

java.io.InputStream. Use this option if the document will

be used as input to a service that can process documents
incrementally (for example, pub.xml:getXMLNodeIterator).
data

Document Data that you want the hp service to submit with

the HTTP request. Specify data using one or more of the
following keys.
Important: When you use more than one key, args is appended
rst, table is appended second, and string is appended last.
Key

Description

args

Document Optional. Name/value pairs that you

want this service to submit to the resource in
url . You can use args to submit data via the
POST, PUT, GET, or HEAD method.
To specify data using args , create one String
element for each name/value pair that you
want to submit, where the element's name
represents the name portion of the pair and the
element's value represents the value portion of
the pair.
When you use args , the hp service will
automatically:
URL-encode name/value pair, so you do not
need to URL-encode the values you specify in
args .
Insert the "&" character between pairs, so you
do not need to include it in args .
Prex the entire query string with the "?"
character if it submits the data in args via a
GET or HEAD. You do not need to include
this character in args .
When you submit data using args , Integration
Server automatically sets the value of the

webMethods Integration Server Built-In Services Reference Version 9.6

111

Even Header
Client Folder

Content-Type header to application/x-www-

form-urlencoded.

If you want to explicitly specify a dierent

Content-Type value, you must submit the
value using the string or bytes variable.
table

String Table Optional. Data that the hp service

will use to construct a query string to submit to
the resource specied in url .
table is similar to args , but it allows you to
submit unnamed values in a query string, not
just name/value pairs.
To specify data using table , create one row for
each value that you want to submit, where
the contents of column 0 of the String Table
represents the name portion of the pair (leave
this column null to submit an unnamed value)
and the contents of column 1 represents the
value portion of the pair.
When you use table , the hp service will
automatically:
URL-encode name/value pair, so you do not
need to URL-encode the values you specify in
table .
Insert the "&" character between the pairs (or
unnamed values) that it constructs, so you do
not need to include it in table .
Prex the entire query string with the "?"
character if it submits the data in table via the
GET method. You do not need to include this
character in table .
When you submit data using table , Integration
Server automatically sets the value of the
Content-Type header to application/x-wwwform-urlencoded. If you want to explicitly
specify a dierent Content-Type, you must
submit your data using the string or bytes
variable.

string

String Optional. Text that you want the hp

service to submit to the resource in url . You can
use string to submit data via the POST, PUT,
GET, or HEAD method.

webMethods Integration Server Built-In Services Reference Version 9.6

112

Odd Header
Client Folder

If you use string to submit data, make sure

that you specify the string exactly as you want
it presented in the HTTP request. (If you are
using the GET or HEAD method, make sure
you URL-encode the contents of string .)
Note: When you use string, the hp service will
automatically prex the entire query string with
"?" if it submits the data in string via a GET or
HEAD. You do not need to include this character
in string .
When performing a POST or PUT, string will
be submied to the resource dened by url as
the body of the request message.
bytes

byte[ ] Optional. Data that you want this service

to submit to the resource in url . You can use
bytes to submit data via the POST or PUT
methods only.
Important: When you use bytes and another
element (args , table , or string ) to specify data, the
service appends the data from the args , table , or
string element to url . The service appends args to
url rst, table second, and string last. The service
encodes the data from the bytes element in the
body of the post. If the stream variable is not null,
bytes is ignored.

mimeStream

Java.io.InputStream Optional. MIME or SMIME

message that you want this service to submit
to the resource in url . A mimeStream is
created by the pub.mime:getEnvelopeStream,
pub.smime:createEncryptedData,
pub.smime:createSignedData,
pub.smime.keystore:createSignedData or services. It
contains both headers and content. The headers
in the mimeStream are appended to the hp
headers.
You can use mimeStream to submit data via the
POST or PUT methods only.

stream

java.io.InputStream Optional. Data that you want

the hp service to submit to the resource in url .
You can use stream to submit data via the POST
or PUT methods only.

webMethods Integration Server Built-In Services Reference Version 9.6

113

Even Header
Client Folder

Important: When you use stream and another

element (args , table , string or bytes ) to specify
data, the service appends the data from the
args , table , or string element to url . The service
appends args to url rst, table second, and string
last. The service encodes the data from the stream
element in the body of the post. If the stream
input is not null, the bytes input is ignored.
encoding

String Optional. Character set in which the

URL data parameters are encoded (args or
table and/or string ). Encoding is required to
correctly convert the String object to bytes
when generating the URL for a post. Specify
an IANA-registered character set (for example,
ISO-8859-1).
If this variable is null, the default JVM
encoding is used. Because string is used in the
body of the post and not used for building the
URL, you do not need to specify encoding for
the data parameter string .

auth

Document Optional. Authorization information that the hp

service will submit if the resource specied in url is protected.
Key

Description

type

String Type of authentication scheme that you

want this service to use when it submits this
request. Set to:
Basic to submit a user name and password.

This is the default.

Bearer to submit authorization information

for an OAuth resource server.

Digest to submit a password digest for

authentication.
user

String User name that this service will submit

when requesting a protected resource.

pass

String Password associated with user .

webMethods Integration Server Built-In Services Reference Version 9.6

114

Odd Header
Client Folder

token

headers

String The access token to submit to the OAuth

resource server. Required only when type is set
to Bearer.

Document Optional. Fields that you want to explicitly override

in the HTTP request header issued by the hp service.
Specify a key in headers for each header eld that you want to
set, where the key's name represents the name of the header
eld and the key's value represents the value of that header
eld.
If you do not set headers , the hp service uses its default
header values.

timeout

String Optional. Time (measured in milliseconds) to wait for

a response from the remote server before timing out and
terminating the request. The default value is dened by the
wa.net.timeout server conguration parameter. The default
value for the wa.net.timeout server conguration parameter
is 300 seconds (30000 milliseconds).
For information about the wa.net.timeout server
conguration parameter, see webMethods Integration Server
Administrators Guide.

maxKeepAlive
Connections

String Optional. Number of client keep alive connections that

you want Integration Server to retain in the client connection
pool it uses for this HTTP connection.
Integration Server establishes a client connection pool for each
protocol (i.e., HTTP or HTTPS), host, and port combination.
How the service uses this input value diers based on whether
a suitable client connection pool already exists for the HTTP
connection.
If a suitable pool already exists, Integration Server uses
a connection from the pool for the HTTP request. If the
specied maxKeepAliveConnections is dierent from what is
currently being used for the pool, Integration Server updates
the pool to use the value you specify.
If a suitable pool does not exist, Integration Server
establishes one, using the maximum connections
dened by this parameter. If you do not specify a
value, the service uses the default value dened by the
wa.net.maxClientKeepAliveConns server conguration
parameter. After establishing the client connection pool,

webMethods Integration Server Built-In Services Reference Version 9.6

115

Even Header
Client Folder

the service uses a connection from the newly established

connection pool to the HTTP request.
keepAliveTimeout

String Optional. Number of seconds that you want Integration

Server to keep an idle connection in the client connection pool
before closing it.
Integration Server establishes a client connection pool for each
protocol (i.e., HTTP or HTTPS), host, and port combination.
How the service uses this input value diers based on whether
a suitable client connection pool already exists for the HTTP
connection.
If a suitable pool already exists, Integration Server uses
a connection from the pool for the HTTP request. If the
specied keepAliveTimeout is dierent from what is currently
being used for the pool, Integration Server updates the pool
to use the value you specify.
If a suitable pool does not exist, Integration Server establishes
one, using the timeout value dened by this parameter.
If you do not specify a value, the service uses the default
value dened by the wa.net.clientKeepAliveTimeout
server conguration parameter. After establishing the client
connection pool, the service uses a connection from the
newly established connection pool to the HTTP request.

newSession

String Optional. Flag indicating whether a new session

will be created for this HTTP request. This parameter
overrides the wa.server.new.hp.session.context server
conguration parameter. For information about the
wa.server.new.hp.session.context server conguration
parameter, see webMethods Integration Server Administrators
Guide.
Set to:
no to use the current session, if one is available, for this HTTP

request. This is the default.

yes to create a new session for this HTTP request.

proxyAlias

String Optional. Name of the proxy alias for the proxy server to
which Integration Server routes the HTTP request.
If you do not specify a proxyAlias , Integration Server routes
the HTTP request through the proxy server specied in the
default HTTP proxy alias. If there is no default HTTP proxy
alias, the action taken by Integration Server depends on the
value specied for the wa.net.proxy.useNonDefaultProxies
parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

116

Odd Header
Client Folder

If the wa.net.proxy.useNonDefaultProxies parameter

is set to true, Integration Server routes the HTTP request
through the proxy server in any congured HTTP
proxy alias. If the Integration Server does not have any
dened HTTP proxy aliases, Integration Server sends
the HTTP request directly to the HTTP server or throws
an exception depending on the seings specied for the
wa.net.proxy.fallbackToDirectConnection parameter.
If the wa.server.proxy.useNonDefaultProxies parameter is
set to false, Integration Server sends the request to the remote
server using a direct connection.
For more information about proxy server usage, refer to
webMethods Integration Server Administrators Guide.
connectTimeout

String Optional. Time (measured in milliseconds) the server

will wait to connect to the remote server before timing out and
terminating the request.
This parameter can be used to override the operating system
parameter that controls the connection timeouts. If a value for
connectTimeout is not specied or is set to 0, the server will
wait for the timeout value dened by the operating system
before terminating the connection request.

useJSSE

String Optional. Whether to enable the use of the Java Secure

Socket Extension (JSSE) socket factory for creating outbound
HTTPS connections. Set to:
yes if the connection requires the use of TLS 1.1 or TLS 1.2.
When set to yes, Integration Server creates the connection

using the Java Secure Socket Extension (JSSE) socket factory.

Note: When useJSSE is set to yes, Integration Server ignores
the connectTimeout parameter.
no if the connection does not require support for TLS 1.1 or
TLS 1.2. When set to no, the connection supports only SSL 3.0

and TLS 1.0. This is the default.

Output Parameters
encodedURL

String The URL that was submied by pub.client:http. This will

contain any argument set in args , table , or string .

header

Document Conditional. HTTP response headers.

webMethods Integration Server Built-In Services Reference Version 9.6

117

Even Header
Client Folder

body

Key

Description

lines

Document Fields in the response header,

where key names represent eld names
and values represent eld values.

status

String HTTP status code of the response.

statusMessage

String HTTP status message of the response.

Document Body of the HTTP response.

Key

Description

bytes

byte[ ] Conditional. Body of the HTTP

response represented as a byte[ ]. bytes
is returned only when the loadAs input
parameter is set to bytes.

stream

java.io.InputStream Conditional. The body

of the HTTP response represented as
an InputStream. stream is returned only
when the loadAs input parameter is set to
stream.

Usage Notes
If url begins with https:, you can use pub.security:setKeyAndChain to specify the certicate
chain. If you do not specify a certicate chain, pub.client:http uses the default outbound
SSL certicate seings to authenticate the resources.
If pub.client:http does not receive a response within the time-out period specied in the
server's wa.net.timeout server conguration parameter, it will throw an exception. For
information about the wa.net.timeout server conguration parameter, see webMethods
Integration Server Administrators Guide.
For the HTTP request, the pub.client:http service uses a client connection from a client
connection pool. When you set the loadAs input parameter to stream so that the service
returns the response body as a stream, the connection remains in use and is not returned
to the connection pool until you close the stream. To close the stream and return the
connection to the pool, you can use the pub.io:close service or the close() method on the
returned stream object.

webMethods Integration Server Built-In Services Reference Version 9.6

118

Odd Header
Client Folder

pub.client.ldap:add
WmPublic. Inserts a new entry into the directory.
Input Parameters
url

String Optional. URL of the directory server to connect to. For

example ldap://servername:389.

principal

String Optional. The principal for the directory server.

credentials

String Optional. Credentials for the directory server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

dn

String The distinguished name of the new entry to add to the

directory.

ars

Document List Optional. LDAP aributes and their corresponding

values. If an aribute is specied more than once, it will be
assigned multiple values. The following example shows how to
specify a user name of John Smith and one nickname.

webMethods Integration Server Built-In Services Reference Version 9.6

119

Even Header
Client Folder

arsData

Document Optional. LDAP aributes and their corresponding

values. If an aribute is specied more than once, it will be
assigned multiple values. The following example shows how to
assign a user name of John Smith with two nicknames.

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only if

the close parameter is set to "no".

Usage Notes
Specify only one of ars or arsData . If you specify both, the service uses ars and
ignores arsData .
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:bind
WmPublic. Performs an LDAP bind operation that associates the connection with the
specied principal.
Input Parameters
url

String URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI

webMethods Integration Server Built-In Services Reference Version 9.6

120

Odd Header
Client Folder

provider documentation or the Oracle JNDI documentation for

more information about parameters you can pass to JNDI.
close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only

if the close parameter is set to "no".

Usage Notes
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:cancelNotification
WmPublic. Cancels a previously created notication request.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation
for more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after

the service nishes. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

121

Even Header
Client Folder

yes to close the connection. This is the default.

no to leave the connection open and available.

dn

String The distinguished name of the entry.

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

scope

String The scope of the search. Must be "object" (only search

the specied directory entry), "onelevel" (only search the
immediate children of the specied directory entry), or
"subtree" (search the directory, its children, and all of their
children).

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only

if the close parameter is set to "no".

Usage Notes
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:compare
WmPublic. Compares the value of an aribute in the LDAP directory with a value
specied by the service.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

webMethods Integration Server Built-In Services Reference Version 9.6

122

Odd Header
Client Folder

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

dn

String The distinguished name of the entry whose aribute value

you want to compare to arValue .

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

arName

String Name of the aribute whose value you want to compare to

arValue .

arValue

String The string to compare against the value of the aribute

identied by arName .

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only if

the close parameter is set to "no".

result

String The result of the compare operation. Can be "true" or

"false".

Usage Notes
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:delete
WmPublic. Removes an entry from the directory.

webMethods Integration Server Built-In Services Reference Version 9.6

123

Even Header
Client Folder

Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

dn

String The distinguished name of the entry to delete.

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only if

the close parameter is set to "no".

Usage Notes
This service does not ag an error if the entry is not deleted. One way to check is to use
pub.client.ldap:search to search for the entry. If the entry is not found, you know it has been
deleted.
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

124

Odd Header
Client Folder

pub.client.ldap:modify
WmPublic. Performs an LDAP modify operation that allows you to specify a list of
aributes with corresponding lists of values to add to, replace, or remove from the
directory entry.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

dn

String The distinguished name of the entry to modify.

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

ars

Document List Optional. For each LDAP aribute to change,

species the aribute name, the values aected, and the action to
perform on those values. The following example shows how to
specify the removal of John Smith's nickname Johnny.

webMethods Integration Server Built-In Services Reference Version 9.6

125

Even Header
Client Folder

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only if

the close parameter is set to "no".

Usage Notes
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:registerNotification
WmPublic. Creates a notication (or "persistent search") that causes Integration Server
to listen for LDAP events. When the notication gets an event, the specied service is
called.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after

the service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

dn

String The distinguished name of the entry to be monitored.

webMethods Integration Server Built-In Services Reference Version 9.6

126

Odd Header
Client Folder

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

scope

String The scope of the search. Must be "object" (only search the
specied directory entry, "onelevel" (only search the immediate
children of the specied directory entry), or "subtree" (search the
directory entry, its children, and all of their children).

service

String The target service to be invoked when the LDAP event is

retrieved.

user

String Optional. Integration Server user to run service (the

target service to be invoked when the LDAP event is retrieved).
If you do not specify a user, the service runs as the Default
user. Make sure user has the permissions necessary to run
the service. Be careful when assigning the user because no
password is required when invoking a service in this manner.
It is recommended that you create a special account just for
invoking the target service.

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only

if the close parameter is set to "no".

Usage Notes
When the pub.client.ldap:registerNotification service creates a notication, Integration Server
listens for four dierent types of events: objectAdded, objectRemoved, objectRenamed,
and objectChanged. If any one of these events is triggered, pub.client.ldap: registerNotification
calls the specied target service and passes these inputs to it:
Pipeline Input

Description

type

One of the following depending on which event was triggered

- "objectAdded", "objectRemoved", "objectRenamed",
"objectChanged".

dn

Distinguished name of the entry that triggered the event.

aributes

Any additional LDAP aributes from the event.

oldDn

Applicable only for objectRenamed event. Distinguished name

of the entry before it was renamed.

webMethods Integration Server Built-In Services Reference Version 9.6

127

Even Header
Client Folder

If an error occurs, pub.client.ldap:registerNotification places an input called "exception" in the

pipeline. This input includes details on the exception that occurred.
Some LDAP servers do not support persistent searches and therefore do not support
notications.
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:rename
WmPublic. Performs an LDAP rename (move) operation allowing you to rename an
entry.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.
no to leave the connection open and available.

connectionHandle

Object Optional. Connection object returned by a previously

invoked LDAP service.

newDn

String The new name for the entry.

webMethods Integration Server Built-In Services Reference Version 9.6

128

Odd Header
Client Folder

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only

if the close parameter is set to "no".

Usage Notes
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.ldap:search
WmPublic. Performs an LDAP search operation with the specied parameters and
returns the results of the search.
Input Parameters
url

String Optional. URL of the LDAP server to connect to.

principal

String Optional. The principal for the LDAP server.

credentials

String Optional. Credentials for the LDAP server.

timeout

String Optional. Connection timeout in milliseconds.

ldapEnv

Record Optional. Key/value parameters to be passed to JNDI

to further dene the connection environment. See your JNDI
provider documentation or the Oracle JNDI documentation for
more information about parameters you can pass to JNDI.

close

String Flag that species whether to close the connection after the
service nishes. Set to:
yes to close the connection. This is the default.

If the close parameter is set to "yes", the connectionHandle

parameter must also be mapped.
no to leave the connection open and available.

webMethods Integration Server Built-In Services Reference Version 9.6

129

Even Header
Client Folder

dn

String The distinguished name indicating the root from to begin

the search.

connectionHandle

Object Required if the close parameter is set to "yes", otherwise it

is optional. Connection object returned by a previously invoked
LDAP service.

scope

String The scope of the search. Must be "object" (only search the
specied directory entry), "onelevel" (only search the immediate
children of the specied directory entry), or "subtree" (search the
directory entry, its children, and all their children).

lter

String The lter string that works with RFC 2254.

countLimit

String Optional. The maximum number of results to return (0, the

default, indicates no limit).

timeLimit

String Optional. The number of milliseconds to wait for the search

to complete (0, the default, indicates to wait forever).

returnAributes

Record Optional. A list of aribute names to return (an empty

array indicates that no results should be returned. A null array,
the default, indicates that all aributes should be returned).

returnObjects

String Optional. Species whether or not objects associated with

the results should be returned. Can be "yes" or "no". The default is
"no".

dereferenceLinks

String Optional. Whether to return the symbolic link to the entry

or the entry itself. Can be "yes"/"no". The default is "yes", which
returns the entry to which the link points.

isDocumentList

String Optional. Whether to return results as a list. Set to:

Yes to return results as a DocumentList containing Documents

(IData). The results are returned in the resultsList output

parameter.

No (the default) to return results as a Document containing

Documents. The results are returned in the results output

parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

130

Odd Header
Client Folder

Output Parameters
connectionHandle

Object Optional. The returned connection object. Returned only if

the close parameter is set to No.

results

Document Conditional. The returned results of the search.

Returned only if isDocumentList is set to No.

resultsList

Document List Conditional. Returned only if isDocumentList is set

to Yes.

Usage Notes
To see if no match was found, check for either:
A results parameter that does not contain a key-value pair.
A resultsList parameter with a size of 0.
When close is set to yes, Integration Server removes the connectionHandle from the
pipeline, but does not close the LDAP connection. To close the LDAP connection, set the
wa.server.ldap.cleanContext server conguration parameter to true. For information
about the wa.server.ldap.cleanContext server conguration parameter, see webMethods
Integration Server Administrators Guide.

pub.client.oauth:executeRequest
WmPublic. Allows Integration Server to access protected resources on a resource server
using an existing Open Authentication (OAuth) access token.
When a client application requires the OAuth protocol to access a users protected
resources on a third-party resource server (for example, Facebook, Google, Twier, or
another Integration Server), the client application must present an access token on behalf
of the user in order to gain access. This service presents the access token to the resource
server on behalf of the user.
Note: To use this service, you must have registered the client with the provider's
authorization server and received an access token. You will use the information given to
you by the provider to congure this service. For information about registering a client
and obtaining an access token, refer to the provider's documentation.
Integration Server uses the Scribe API, a simple open source client implementation, to
connect to OAuth providers. The Scribe API provides client implementations for many
providers such as Facebook, Google, and Twier. For information about using the Scribe
API, see the Usage Notes.

webMethods Integration Server Built-In Services Reference Version 9.6

131

Even Header
Client Folder

Input Parameters
provider

String Name of the service provider to which the client will

connect. Integration Server uses this parameter to determine
which OAuth client implementation in the Scribe library to use
when issuing requests.
Possible values are IntegrationServer and Other (case
insensitive).
Note: If set to Other, you must specify a value for providerClass .

providerClass

String Name of a class that implements the org.scribe.builder.api.Api

interface.
This parameter is required only when the provider parameter is
set to Other.
Note: The org.scribe.builder.api.Api interface is part of the Scribe API.
It facilitates the use of the pub.client.oauth:executeRequest service to
connect to providers other than IntegrationServer. For more
information about org.scribe.builder.api.Api see the Usage Notes.

clientID

String The client identier assigned to the client by the provider.

The clientID is used to authenticate the client to the provider.
The value is assigned by the provider at registration time.

clientSecret

String The secret assigned to the client when it registered with

the provider.
Use this parameter to specify either the client secret or the
key to the client secret in the outbound password store. For
information about using the outbound password store, see the
Usage Notes.

accessToken

String The access token assigned to the client application when it

registered with the provider.
Note: The process for obtaining the accessToken varies depending
on the provider. For information about obtaining the accessToken ,
refer to your provider's documentation.
Use this parameter to specify either the access token or the
key to the access token in the outbound password store. For
information about using the outbound password store, see the
Usage Notes.

webMethods Integration Server Built-In Services Reference Version 9.6

132

Odd Header
Client Folder

acccessTokenSecret

String Optional. The access token secret assigned to the client

application when it registered with the provider.
Note: The process for obtaining the accessTokenSecret varies
depending on the provider. For information about obtaining the
accessTokenSecret , refer to your provider's documentation.
Use this parameter to specify either the access token secret or the
key to the access token secret in the outbound password store.
For information about using the outbound password store, see
the Usage Notes.
Note: Not all providers use an access token secret. If the provider
issued a secret with the token, you must specify it with the
accessTokenSecret parameter.

resourceUri

String The URI given to the client application when it registered

with the provider.
The client application uses this URI when issuing requests to
the provider. It points to the resource that the client application
wants to access on the provider.

method

String The HTTP method Integration Server will use to issue the
request to the provider.
Possible values are get, post, put, and delete.

headers

Document List Optional. One or more name/value pairs to add to

the header of the request sent to the provider.
If the provider requires a request header, you must provide a
value.

queryString
Parameters

Document List Optional. One or more name/value pairs to add to

the URL of the get request sent to the provider.

bodyParameters

Document List Optional. One or more name/value pairs to add to

the body of the request sent to the provider.

requestDataType

String Optional. If supplying data with the request to the

provider, indicates the data type of the requestData parameter. If
set to:
bytes, requestData must be a byte[]. This is the default.
string, requestData must be a java.lang.String.

webMethods Integration Server Built-In Services Reference Version 9.6

133

Even Header
Client Folder

requestData

Object Optional. Data to include in the body of the request sent to

the provider. The value can be a string or a byte[].
The data type of requestData must match what is specied
by the requestDataType parameter. requestData is ignored if
bodyParameters is specied.

responseDataType

String Optional. Indicates the data type of the responseData

output parameter. Set to:
stream to return the responseData as a java.io.InputStream. This
is the default.
bytes to return the responseData as a byte[].
string to return the responseData as a java.lang.String,
constructed using the default platform encoding (indicated
by the le.encoding Java system property, or UTF-8 if
le.encoding is not set).

Output Parameters
responseData

Object The response from the provider. If the responseDataType is

set to:
stream, responseData is a java.io.InputStream.
bytes, responseData is a byte[].
string, responseData is a java.lang.String, constructed using

the default platform encoding (indicated by the le.encoding

Java system property, or UTF-8 if le.encoding is not set).
Usage Notes
Since the values for the clientSecret , accessToken , and accessTokenSecret parameters
contain sensitive data, you might want to consider storing their values in the
Integration Server outbound password store. For information about services
you can use to store these values in the outbound password store, see the
pub.security.outboundPasswords in the About the Security Elements folder.
If you decide to use the outbound password store, the value for each parameter
(clientSecret , accessToken , and accessTokenSecret ) must match the key you supplied in
the pub.security.outboundPasswords services. Integration Server uses that key to retrieve
the values from the store, then uses the values to send the request to the provider.
If you decide not to use the outbound password store, Integration Server sends
the request to the provider using the values you supply with the clientSecret ,
accessToken , and accessTokenSecret parameters.

webMethods Integration Server Built-In Services Reference Version 9.6

134

Odd Header
Client Folder

You can use this service to connect to OAuth providers other than Integration
Server by seing the provider parameter to Other and the providerClass parameter
to the name of an org.scribe.builder.api.Api implementation. The org.scribe.builder.api.Api
interface is dened in the Scribe open source API. For this approach, Software AG
recommends the following:
That you download the Scribe API source code from the GitHub website. You
can either browse the code or generate the Javadoc for the Scribe classes using
the following command:
javadoc -sourcepath your_scribe_install_dir/src/main/java -d
your_destination_dir org.scribe.builder.api

That you check the Scribe OAuth library to see if an implementation for
the provider that you want to use already exists. Scribe provides client
implementation for many providers.
Important: If an implementation already exists but the provider has changed its
interface and the implementation in the Scribe library no longer works, you can
either modify the implementation yourself or request an update from the author
of Scribe.
If your provider supports OAuth 2.0, then extend org.scribe.builder.api.DefaultApi20. If
your provider supports OAuth 1.0a, then extend org.scribe.builder.api.DefaultApi10a.

pub.client.sftp:cd
WmPublic. Changes the working directory on the remote SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

path

String Absolute or relative path of the directory that you want as the
working directory on the remote SFTP server.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

webMethods Integration Server Built-In Services Reference Version 9.6

135

Even Header
Client Folder

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chgrp
WmPublic. Changes the group ownership of one or more remote les.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

groupId

String Numeric group identier of the group to which you want

to transfer ownership of the remote les.

path

String Absolute or relative path of the remote les.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chmod
WmPublic. Changes permissions of one or more remote les.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

mode

String The permission mode to apply to the remote le (for

example, 777).

path

String Absolute or relative path of the remote les.

webMethods Integration Server Built-In Services Reference Version 9.6

136

Odd Header
Client Folder

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:chown
WmPublic. Changes the owning user of one or more remote les.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

uid

String Numeric user ID of the new owning user of the le.

path

String Absolute or relative path of the remote les.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:get
WmPublic. Retrieves a le from a remote SFTP server and saves it on the local machine.

webMethods Integration Server Built-In Services Reference Version 9.6

137

Even Header
Client Folder

Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

remoteFile

String Absolute or relative path of the remote le.

localFile

String Optional. Absolute or relative path of the local le.

If localFile is not specied, the pub.client.sftp:get service returns
the retrieved le in the output parameter contentStream (as a
java.io.InputStream object).

mode

String Optional. Species how the retrieved le is to be saved to

the local le. Use this parameter only if you have specied a value
for localFile . Set to:
overwrite to overwrite the contents of the local le with the

contents of the remote le. This is the default.

append to append the entire contents of the remote le to the

local le.

resume to resume writing the contents of the remote le to the

local le from the point at which the writing stopped during

previous SFTP sessions.
Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

contentStream

Object Conditional. A java.io.InputStream object.

The pub.client.sftp:get service returns the retrieved le in the output
parameter contentStream (as a java.io.InputStream object) if
localFile is not specied.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

webMethods Integration Server Built-In Services Reference Version 9.6

138

Odd Header
Client Folder

pub.client.sftp:login
WmPublic. Connects to a remote SFTP server and logs in with the specied SFTP user
alias.
Important: You must use this service to initiate an SFTP session before using most other
pub.client.sftp services.
Input Parameters
userAlias

String Alias containing the SFTP client conguration for an SFTP

user account. Integration Server creates a new session each time it
logs on to the SFTP server and returns the session key to the user.

reuseSession

String Flag indicating whether or not Integration Server reuses a

session that is already open for the specied user alias. Set to:
true to reuse the session that is already open for the specied user

alias. If no session is open for this user alias, the pub.client.sftp:login

service will create a new session and return the key for this new
session.
false to create a new session for the specied user alias. This is

the default.
Output Parameters
sessionKey

String Unique key for the current SFTP session. Most other
pub.client.sftp services require this session key to execute.

returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:logout
WmPublic. Logs o the user from the SFTP server and ends the current SFTP session.

webMethods Integration Server Built-In Services Reference Version 9.6

139

Even Header
Client Folder

Input Parameters
String Unique key for the current SFTP session. The sessionKey
parameter is returned by the pub.client.sftp:login service.

sessionKey

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:ls
WmPublic. Retrieves the remote directory listing of the specied path. If path is not
specied, the pub.client.sftp:ls service retrieves the le listing of the current remote
directory. The pub.client.sftp:ls service also retrieves additional details such as permissions
and ownership information.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey
parameter is returned by the pub.client.sftp:login service.

path

String Optional. Absolute or relative path of the remote directory.

If no path is specied, the pub.client.sftp:ls service retrieves the
directory listing of the current remote directory.
You can use the wildcard characters asterisk (*) and question mark
(?) after the last slash mark (/) to view all remote directories that
match the specied path.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

webMethods Integration Server Built-In Services Reference Version 9.6

140

Odd Header
Client Folder

dirList

String List List of directories matching the paern specied in the

path parameter.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:mkdir
WmPublic. Creates a new remote directory.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey
parameter is returned by the pub.client.sftp:login service.

path

String Absolute or relative path of the remote directory where you

want to create a new directory.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:put
WmPublic. Transfers a le to a remote SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

contentStream

java.io.InputStream Optional. Data to be transferred to the remote

le.

webMethods Integration Server Built-In Services Reference Version 9.6

141

Even Header
Client Folder

localFile

String Optional. Name of the local le to be appended to the remote

le. Use localFile only if contentStream is not specied.

remoteFile

String Optional. Absolute or relative path of the remote le to

which the local le is to be appended.

mode

String Optional. Species how the local le is to be transferred to

the remote SFTP server. Set to:
overwrite to overwrite the contents of the remote le with the

contents of the local le. This is the default.

append to append the entire contents of the local le to the

remote le.

resume to resume writing the contents of the local le to the

remote le from the point the writing was stopped during

previous SFTP sessions.
Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
If you specify contentStream , you must specify remoteFile . In this case, localFile is
optional.
If you specify localFile , then remoteFile and contentStream are optional. In this case, the
remote le will be given the same name as the local le.
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:pwd
WmPublic. Displays the remote working directory in the SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

webMethods Integration Server Built-In Services Reference Version 9.6

142

Odd Header
Client Folder

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

path

String Absolute or relative path of the working directory on the

remote SFTP server.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:rename
WmPublic. Renames a le or directory on a remote SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

oldPath

String Fully qualied name of the le you want to rename (for

example, temp/oldname.txt).

newPath

String New fully qualied name for the le (for example, temp/

newname.txt).

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

webMethods Integration Server Built-In Services Reference Version 9.6

143

Even Header
Client Folder

pub.client.sftp:rm
WmPublic. Deletes one or more remote les on the SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

path

String Absolute or relative path of the le you want to delete.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:rmdir
WmPublic. Deletes one or more remote directories on the SFTP server.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

path

String Absolute or relative path of the directory you want to delete.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

webMethods Integration Server Built-In Services Reference Version 9.6

144

Odd Header
Client Folder

Usage Notes
The remote directories that you want to delete must be empty.
You cannot execute SFTP commands in parallel using the same session key.

pub.client.sftp:symlink
WmPublic. Creates a symbolic link between the old path and the new path of a le.
Input Parameters
sessionKey

String Unique key for the current SFTP session. The sessionKey is
returned by the pub.client.sftp:login service.

oldPath

String Old path of the le for which you want to create a symbolic link.

newPath

String New path of the le to which the symbolic link should point.

Output Parameters
returnCode

String Standard SFTP protocol return code.

returnMsg

String Text message describing the return code.

Usage Notes
You cannot execute SFTP commands in parallel using the same session key.

pub.client:smtp
WmPublic. Sends a MIME-type e-mail message.
You may aach one or more content objects or les to the message.
Input Parameters
to

String Optional. E-mail address of the receiver. If you specify

multiple addresses, separate them with commas.

cc

String Optional. E-mail addresses of additional receivers. If you

specify multiple addresses, separate them with commas.

webMethods Integration Server Built-In Services Reference Version 9.6

145

Even Header
Client Folder

bcc

String Optional. E-mail addresses of additional receivers. If you

specify multiple addresses, separate them with commas.

subject

String Optional. Subject of the message.

subjectCharset

String Optional. The character set used to encode the MIME message
headers (including subject). If subjectCharset is not specied, then
charset is used. If charset is not specied, the value in the server
conguration parameter wa.server.email.charset is used. If that
parameter is not set, the utf-8 encoding is used.

charset

String Optional. The character encoding of the body text. If you do

not specify the value of charset , the value in the server conguration
parameter wa.server.email.charset is used. If that parameter is not
set, the utf-8 encoding is used.

from

String Optional. E-mail address of the sender. If you do not specify

a from value, Integration Server uses the value specied for the
mail.smtp.from JVM property. If no value is specied for that
property, Integration Server uses the default value, user@servername ,
where user is the operating system user ID, and servername is the
host name of the Integration Server.

mailhost

String SMTP host name for outbound messages. For example:

smtp.webMethods.com

If no value is provided for the mailhost parameter, Integration

Server uses the value of the system property mail.smtp.host in the
startup.bat (startup.sh) le as the mailhost value.
mailhostPort

String Optional. The number of the port on which the SMTP host
listens. This parameter does not need to be set if the host listens on
port 25 (the standard SMTP port).

auth

Document Optional. Authorization information that the SMTP service

will submit.
Key

Description

user

String User name that this service will

submit when requesting a protected
resource.

pass

String Password associated with user .

webMethods Integration Server Built-In Services Reference Version 9.6

146

Odd Header
Client Folder

secure

Document Optional. Parameters specifying the security protocol

and truststore information for certicate validation that Integration
Server uses when communicating with the SMTP server port.
Key

Description

transportLayerSecurity

String Type of security protocol Integration

Server uses when communicating with the
SMTP server port. Set to:
none to use a non-secure mode when

communicating with the port on the

SMTP sever. This is the default.

explicit to use explicit security when

communicating with the port on the

SMTP server. With explicit security,
Integration Server establishes an unencrypted connection to the e-mail server
and then switches to the secure mode.
implicit to use implicit security when

communicating with the port on the

SMTP server. With implicit security,
Integration Server always establishes an
encrypted connection to the e-mail server.
truststoreAlias

String Optional. Alias for the truststore

that contains the list of certicates that
Integration Server uses to validate the
trust relationship.If you do not specify a
truststore alias, the default truststore alias
will be used.

body

String Optional. The content of the message.

mimeStream

java.io.InputStream Optional. MIME or S/MIME message that

you want to send in the e-mail. A mimeStream is created by
the pub.mime:getEnvelopeStream, pub.smime:createEncryptedData,
pub.smime:createSignedData, or pub.smime.keystore:createSignedData
services. It contains both headers and content. If the mimeStream
already contains the from, to, and subject headers, you do not need
to pass them as individual inputs to this service.

aachments

Document List Optional. Aachments to the message. Each

aachment denes one message part in a multi-part message.

webMethods Integration Server Built-In Services Reference Version 9.6

147

Even Header
Client Folder

Key

Description

contenype

String MIME type of the message. For

example:
application/x-edi-message

content

byte[ ], String, or java.io.InputStream Content

of the message.

lename

String Name to assign to the aachment.

If you do not specify aachment/content ,
the parameter species the le name of a
local le to aach to the message. In other
words:
If you specify aachment/content and
aachments/lename , the service uses the
value of aachments/lename as the name
to assign to the aachment specied by
aachment/content .
If you specify aachments/lename ,
but not aachment/content , the service
aaches the local le specied by
aachments/lename .

properties

encoding

String Optional. Encoding of the message.

For example: base64 or 7bit. If encoding is
not specied, 7bit is used.

charset

String Optional. Character set encoding of

the aachment. This value is added to the
Content-Type header for the aachment.
If charset is not specied, the value in
the server conguration parameter
wa.server.email.charset is used. If that
parameter is not set, the utf-8 encoding is
used.

Document List Optional. SMTP system properties to send to

the SMTP server. This parameter overrides the seings on the
wa.cong.systemProperties server conguration parameter. If you
omit this properties parameter, Integration Server uses the seings
specied on the wa.cong.systemProperties server conguration
parameter.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

148

Odd Header
Client Folder

name

Name of the SMTP system property.

value

Value to specify for the SMTP property.

Output Parameters
status

String Final status of service.

Usage Notes
Any one of the recipient elds, that is the to , cc , or the bcc parameter, must be dened.
If you are using lename to aach a le to the message and the le is not a
plain text le, you must set the contenype and encoding . For example, to aach
IntegrationServer_directory \instances\instance_name \mydir\myle.doc to a pub.client:smtp
service, you would invoke the service with the following values in aachments :
contenype :application/msword
lename :instances/instance_name/mydir/myfile.doc
encoding :base64

pub.client:soapClient
WmPublic. Creates and sends SOAP 1.1 and SOAP 1.2 messages over HTTP, HTTPS, or
JMS transports for any style/use combination supported by Integration Server.
Input Parameters
address

String String specifying the URI of the web service

endpoint. If you are submiing the request to an
Integration Server, remember to direct it to the default
SOAP processor (ws) as shown in the following example:
http://rubicon:5555/soap/ws/example:calculator

request

Document The input parameters that are to be passed to the

web service.

wsdName

String The name of the consumer web service descriptor

that contains the operation you want to invoke.

wsdBinderName

String The name of a binder that contains information

to use to create and send the request. This binder must

webMethods Integration Server Built-In Services Reference Version 9.6

149

Even Header
Client Folder

be in the consumer web service descriptor specied in

wsdName .
Note: The consumer web service endpoint alias assigned to
a binder indicates which proxy server Integration Server
uses to send the request. For more information about proxy
server usage and web service endpoint aliases, see the
webMethods Integration Server Administrators Guide guide.
wsdOperationName

String The name of the operation that you want to invoke.

This operation must be contained in the binder specied in
wsdBinderName .

targetInputSignature

String Fully qualied name of the IS document type to use

to validate and encode the contents of request .

targetOutputSignature

String Fully qualied name of the IS document type to use

to validate and decode the output value returned by the
web service.

soapHeaders

Document Optional. Header documents included in the

SOAP request as SOAP headers.

transportHeaders

Document Optional. Transport header elds that you

want to explicitly set in the request issued by the
pub.client:soapClient service. Specify a key in transportHeaders
for each header eld that you want to set, where the key's
name represents the name of the header eld and the key's
value represents the value of that header eld.
The names and values supplied to transportHeaders must
be of type String. If a transport header has a name or value
that is not of type String, the header will not be included in
the message.
The headers that you pass in to transportHeaders vary
depending on the transport used to send the SOAP
message. The supplied wsdBinderName determines
the transport. For more information about specifying
transportHeaders , refer to the Usage Notes.

method

Document Optional. The QName of the requested

procedure. The name is dened as follows:
Key

Value

webMethods Integration Server Built-In Services Reference Version 9.6

150

Odd Header
Client Folder

namespaceName

String Namespace portion of the

procedure's QName.

localName

String Local portion of the

procedure's QName.

Note: The method parameter applies when style is RPC.

auth

Document Optional. Parameters specifying the credentials

that are to be submied to the server specied in address .
Integration Server allows two levels of authorization
credentials: transport level and message level. Each
element is dened as follows:
Key

Description

transport

Document Optional. Transport level

authorization parameters.
Key

Description

type

String Optional.
Type of
authentication that
the service will
perform. Set to:
Basic to submit

a user name and

password. This is
the default.
Digest to submit

a password digest
for authentication.
user

String Optional.
User name that this
service will use if
one is requested.

pass

String Optional.
Password that this
service will submit
if one is requested.

webMethods Integration Server Built-In Services Reference Version 9.6

151

Even Header
Client Folder

serverCerts

Document Optional.
The message
signer's private
key and certicate
chain.
privateKey Object
The SOAP message
signer's private
key.
certChain Object List
A list containing
the signer's
complete certicate
chain, where
element 0 in the
list contains the
signer's certicate
and element 1
contains the CA's
certicate.

message

Document Optional. Message level

authorization parameters.
Key

Description

user

String Optional.
User name that this
service will use if
one is requested.

pass

String Optional.
Password that this
service will submit
if one is requested.

serverCerts

Document Optional.
The message
signer's private
key and certicate
chain.
privateKey Object
The SOAP message
signer's private
key.

webMethods Integration Server Built-In Services Reference Version 9.6

152

Odd Header
Client Folder

certChain Object List

A list containing
the signer's
complete certicate
chain, where
element 0 in the
list contains the
signer's certicate
and element 1
contains the CA's
certicate.
partnerCert

timeout

Object Optional.
The partner's
complete certicate
chain, where
element 0 in the
list contains the
message signer's
certicate and
element 1 contains
the CA's certicate.

String Optional. Time (measured in milliseconds) to wait

for a response from the server hosting the web service
before timing out and terminating the request.
A value of 0 means Integration Server waits for a response
indenitely. If the connection to the host or JMS provider
ends before Integration Server receives a response, the
service ends with an exception and a status code of 408.
If this parameter is not specied, or an invalid (nonnumeric) value is specied, Integration Server uses one of
the following values:
For HTTP, Integration Server uses the value of the
wa.server.SOAP.request.timeout server conguration
parameter as the timeout value
For JMS, Integration Server uses the value of the
wa.server.soapjms.request.timeout server conguration
parameter as the timeout value.
For more information about
wa.server.SOAP.request.timeout and
wa.server.soapjms.request.timeout server conguration
parameter, see webMethods Integration Server Administrators
Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

153

Even Header
Client Folder

Integration Server ignores timeout if the name/value pair

jms.async= true is passed in to transportHeaders .

String Optional. Species one of the following:

soapAction

If soapProtocol is set to SOAP 1.1 Protocol, species the

value to which you want to set the SOAPAction HTTP
header.
If soapProtocol is set to SOAP 1.2 Protocol, species the
value to which you want to set the action aribute in the
Content-Type header.
Integration Server ignores soapAction in either of the
following situations:
The Content-Type header is passed in to
transportHeaders and soapProtocol is set to SOAP 1.2
Protocol.
The soapAction header is passed into transportHeaders
and soapProtocol is set to SOAP 1.1 Protocol.
soapProtocol

String Optional. Indicates the SOAP protocol the service

uses to send messages. Valid values are SOAP 1.1
Protocol or SOAP 1.2 Protocol.

encoding

String Optional. Species the encoding method. Default

value is UTF-8.
Integration Server ignores encoding if the Content-Type
header is passed in to transportHeaders .

Output Parameters
soapResponseData

Object A SOAP object containing the SOAP response message

returned by the server specied in address .

response

Document Output parameters returned from the web service.

header

Document Conditional. Headers from the response and request

messages.
header contains the following keys:
Key

Value

webMethods Integration Server Built-In Services Reference Version 9.6

154

Odd Header
Client Folder

requestLines

Document Conditional. Header elds

from the request message. Each key in
requestLines represents a line (eld) in
the request header. Key names represent
the names of header elds. The keys'
values are Strings containing the values
of the elds.
The contents of the requestLines
document are not identical to
transportHeaders . The transport can add,
remove, or alter specic headers while
processing the request.
Whether or not the web service
connector returns the requestLines
parameter depends on the success or
failure of the pub.client:soapClient service.
In the case of failure, the point at
which the failure occurs determines the
presence of the requestLines parameter.
For more information, see the usage
notes for this service.
For the HTTP or HTTPS transports, the
requestLines parameter will not contain
any HTTP headers that the transport
mechanism added or modied when
sending the request.
For the JMS transport, each key in
requestLines represents a JMS message
header. Key names represent the names
of header elds. Key values are Strings
containing the values of the header
elds. The JMS provider populates
some JMS message header elds after it
successfully receives the JMS message.
Additionally, the Integration Server
specic run-time properties (properties
that begin with the jms. prex) are
not returned in JMS transport, each key
in requestLines . The JMS provider uses
the information in these properties to
populate the JMS message header elds
that correspond to the properties.

lines

Document Header elds from the

response. Each key in lines represents a
eld (line) of the response header. Key

webMethods Integration Server Built-In Services Reference Version 9.6

155

Even Header
Client Folder

names represent the names of header

elds. The keys' values are Strings
containing the values of the elds.
Whether or not the pub.client:soapClient
service returns the lines parameter
depends on the success or failure of the
service. In the case of failure, the point
at which the failure occurs determines
the presence of the lines parameter. For
more information, see the usage notes
for this service.
For the HTTP or HTTPS transports, the
lines parameter contains any HTTP/
HTTPS headers present in the response.
For the JMS transport, the lines
parameter contains the JMS headers
present in the response.

soapStatus

status

String Status code from the request,

returned by the underlying transport.
response. For more information about
status codes returned by the service, see
the usage notes for this service.

statusMessage

String Status message returned by the

transport. For more information about
status messages returned by the service,
see the usage notes for this service.

String Flag indicating whether the SOAP request message was

processed successfully.
A value of...

Indicates that...

The remote server successfully

processed the SOAP request and
returned a SOAP response message.

The remote server returned a SOAP

fault, indicating that the SOAP request
was received but was not processed
successfully.

The server returned an error that was

not a SOAP fault. This indicates that

webMethods Integration Server Built-In Services Reference Version 9.6

156

Odd Header
Client Folder

some type of HTTP error occurred

(often, an HTTP 404). You can check the
status eld in header to determine the
type of HTTP error that occurred.
Usage Notes
If the address begins with https:, you must specify a private key and certicate chain.
You can use the auth/transport/serverCerts parameters to do so. If you do not specify them
using the auth/transport/serverCerts parameters, pub.client:soapClient uses the web service
endpoint alias specied in the binder. If the endpoint alias does not have an associated
private key and certicate chain, then the default outbound SSL certicate seings are
used to authenticate the resources.
As part of executing pub.client:soapClient, Integration Server executes any service handlers
assigned to the consumer web service descriptor specied in wsdName .
When a document type contains a String variable that represents a required aribute
(meaning that the variable name starts with the "@" symbol and the Required property is
set to True in Designer) and the input document does not contain the required aribute,
Integration Server adds an empty aribute during document encoding. For example,
if the document type contains a required String variable named @myAribute but
@myAribute is missing from the input document, Integration Server adds myAttribute
="" to the XML document.
Note: Because empty xmlns aributes are invalid, if the document type contains a
required String variable named @xmlns and the input document does not specify a
value for the @xmlns aribute, Integration Serverdoes not add xmlns="" to the XML
document.
Keep the following points in mind when specifying transportHeaders for HTTP or
HTTPS:
For any header name/value pair supplied in transportHeaders , Integration Server
simply passes through the supplied headers and does not perform any validation for
the headers.
If you do not set transportHeaders or do not specify the following header elds in
transportHeaders , Integration Server adds and species values for the following
header elds:
Accept
Authorization
Connection
Content-Type
Host
SOAPAction (Added when soapProtocol is SOAP 1.1 only)

webMethods Integration Server Built-In Services Reference Version 9.6

157

Even Header
Client Folder

User-Agent

Important: Pass in the preceding headers to transportHeaders only if you are an

experienced web service developer. Incorrect header values can result in failure
of the HTTP request.
If you specify Content-Type in transportHeaders , Integration Server ignores the
value of the encoding input parameter.
If you specify Content-Type in transportHeaders and the soapProtocol input
parameter is set to SOAP 1.2, Integration Server ignores the value of the soapAction
input parameter.
If you specify the SOAPAction header in transportHeaders and the soapProtocol input
parameter is set to SOAP 1.1 Protocol, Integration Server ignores the value of the
soapAction input parameter.
If MTOM processing converts any portion of the SOAP request to an MTOM/
XOP aachment, it will overwrite the Content-Type value supplied to the
transportHeaders input.
Integration Server sets the value of Content-Length automatically and overrides
any value passed in to transportHeaders .
Integration Server automatically adds the Cookie header to the HTTP header and
supplies any cookies established between Integration Server and the HTTP server
with which it is interacting. If you supply the Cookie header to transportHeaders ,
Integration Server prepends the values you supply to the already established Cookie
header value.
The following headers are considered to be standard and require the specied
capitalization: Accept, Authorization, Connection, Content-Type, Cookie, Host,
SOAPAction, User-Agent.
Using capitalization other than that which is specied results in undened behavior.
Supplying duplicate entries for any standard header results in undened behavior.
Keep the following points in mind when specifying transportHeaders for JMS:
Specify a key in transportHeaders for each header eld that you want to set,
where the keys name represents the name of the header eld and the keys value
represents the value of that header eld.
You can specify the following JMS message header elds in transportHeaders :
JMSCorrelationID
JMSType
Note: The JMSCorrelationID and JMSType names are case-sensitive.
You can specify the following JMS-dened properties in transportHeaders :
JMSXGroupID

webMethods Integration Server Built-In Services Reference Version 9.6

158

Odd Header
Client Folder

JMSXGroupSeq
If the value of JMSXGroupSeq is not an integer, Integration Server ignores the
name/value pair and does not place it in the message header.
Note: The JMSXGroupID and JMSXGroupSeq names are case-sensitive.
The JMSX prex is reserved for JMS-dened properties. If a header whose name
starts with JMSX is passed into transportHeaders and it is not named JMSXGroupID
or JMSXGroupSeq, Integration Server generates a fault and returns it to the service.
You can set any provider-specic property whose name starts with JMS_ in
transportHeaders . Integration Server maps a supplied name/value pair whose
name starts with JMS_ directly to a JMS message property. Because the JMS
standard reserves the prex JMS_<vendor_name> for provider-specic properties,
Integration Server does not validate the name or value of this content.
Note: The JMS provider determines which provider-specic properties to accept
and include in the JMS message properties. For more information about providerspecic message properties how the JMS provider handles them, review the JMS
provider documentation.
You can use transportHeaders to specify run-time properties that aect the values
of the JMS message and JMS message headers. The following table identies these
properties and indicates the JMS message header elds aected by each property.
Property Name

Description

jms.async

Indicates whether this is a synchronous or asynchronous

request/reply. This run-time property does not aect a JMS
message header eld.
Note: This property applies when pub.client:soapClient calls an
operation with an In-Out message exchange paern only
Value

Description

true

Indicates this is an asynchronous

request/reply. Integration Server
does not wait for a response message
before executing the next step in the
ow service.
If jms.async is true, Integration
Server ignores the timeout input
parameter.

false

Default. Indicates this is a

synchronous request/reply.

webMethods Integration Server Built-In Services Reference Version 9.6

159

Even Header
Client Folder

Property Name

Description
Integration Server waits for a
response before executing the next
step in the ow service.

jms.deliveryMode

Species the message delivery mode for the

message. Integration Server uses this value to set the
JMSDeliveryMode header.
Value

Description

PERSISTENT

Indicates the request message is

persistent.

Default. Indicates the request

message is persistent.

NON_PERSISTENT

Indicates the request message is not

persistent.

Indicates the request message is not

persistent.

Note: If the jms.deliveryMode is not one of the above values,

Integration Server ignores the name/value pair and uses the
default value of 2.
jms.messageType

Message type identier for the message. Integration

Serveruses this value to set the JMSType header.
Specify one of the following:
BytesMessage
TextMessage
Note: If thejms.messageTypevalue is not BytesMessage or
TextMessage, Integration Server ignores the name/value pair
and uses the default value of BytesMessage

jms.timeToLive

Length of time, in milliseconds, that the JMS provider

retains the message. A value of 0 means that the message
does not expire.
The JMS provider uses this value to set the JMSExpiration
header in the sent JMS message.

webMethods Integration Server Built-In Services Reference Version 9.6

160

Odd Header
Client Folder

Property Name

Description
Note: If the jms.timeToLivevalue is not a valid Long,
Integration Server ignores the property and uses the default
value of 0.

jms.priority

Species the message priority. The JMS standard denes

priority levels from 0 to 9, with 0 as the lowest priority and
9 as the highest.
Integration Server uses this value to set the JMSPriority
header.
If the jms.priority value is not a value between 0 to 9,
Integration Server ignores the property and uses the
default value of 4.

The lowercase jms. prex is reserved for run-time properties used by Integration
Server. If a header starts with jms.and is not one of the jms. properties dened
by Integration Server, Integration Server ignores the property.
The header information returned when pub.client:soapClient executes an operation in a web
service descriptor created on Integration Server version 8.2 or later varies depending on
the following:
The transport used to send the SOAP message which is determined by the
wsdBinderName
The success or failure of the pub.client:soapClient service and if failure occurs, the point
at which that happens
The message exchange paern for the operation specied in wsdOperationName
Note: The same conditions that aect the contents of header also determine whether the
soapResponseData contains a SOAP response, a SOAP fault, or an exception.
The following table identies the basic success and failure scenarios when
pub.client:soapClient service executes an operation in a web service descriptor created
on Integration Server version 8.2 or later and the header information that would be
returned in each scenario. The table also indicates whether the scenario results in a
SOAP response, SOAP fault, or exception being returned in soapResponseData .
Note: JMS status codes as well as the status code 900 are specic to Integration Server
and are not derived from any standard.
Use Case
The pub.client:soapClient service fails before sending the SOAP request.

webMethods Integration Server Built-In Services Reference Version 9.6

161

Even Header
Client Folder

Parameter

Description

status

900

statusMessage

Error occurred while preparing SOAP request

requestLines returned?

Yes, if the web service connector created the SOAP

request successfully but execution failed before
sending the request.

lines returned?

No

soapResponseData

Contains an exception.

Use Case
The pub.client:soapClient service fails while sending the SOAP request.
Parameter

Description

status

For HTTP, the status code will be the value returned

by the HTTP server.
For JMS, the status code will be 400.

statusMessage

For HTTP, the status message will be the message

returned by the HTTP server.
For JMS, the status message will be: Error occurred
while sending request to JMS provider.

requestLines returned?

Yes

lines returned?

For HTTP, lines may be returned. For example, when

the provider returns a status code in the 300 range or
400 range, it is possible that the provider populated
response headers.
For JMS, lines will not be returned.

soapResponseData

Contains an exception.

Use Case

webMethods Integration Server Built-In Services Reference Version 9.6

162

Odd Header
Client Folder

The pub.client:soapClient service fails while sending the SOAP request because a
timeout occurs.
Parameter

Description

status

408

statusMessage

Timeout

requestLines returned?

Yes

lines returned?

No

soapResponseData

Contains an exception.

Use Case
The pub.client:soapClient service executes successfully.
Parameter

Description

status

For HTTP, the status code will be the value returned

by the HTTP server. The status code will typically be in
the 200 range.
For JMS and an In-Out or Robust In-Only operation,
the status code will be 200.
For JMS and an In-Only operation, the status code will
be 202.

statusMessage

For HTTP, the status message will be the message

returned by the HTTP server.
For JMS, the status message will be: OK

requestLines returned?

Yes

lines returned?

Depends on the message exchange paern (MEP) of

the operation.
For In-Only and Robust In-Only, lines is not returned.
For In-Out, lines is returned.

soapResponseData

Contains the SOAP response for In-Out MEP only.

webMethods Integration Server Built-In Services Reference Version 9.6

163

Even Header
Client Folder

Use Case
The pub.client:soapClient service executes successfully but the JMS provider is not
available, causing Integration Server to write the JMS message to the client side
queue.
Note: This use case applies to JMS only. It occurs only when the client side queue is
enabled for the JMS binder specied in wsdBinderName .
Parameter

Description

status

300

statusMessage

Message wrien to the client side queue.

requestLines returned?

Yes

lines returned?

No.

soapResponseData

Not returned.

Use Case
The pub.client:soapClient service sends the SOAP request successfully but receives a
SOAP fault from the web service provider.
Parameter

Description

status

For HTTP, the status code will be the value returned

by the HTTP server. The status code will typically be in
the 500 range.
For JMS, the status code will be 500.

statusMessage

For HTTP, the status message will be the message

returned by the HTTP server.
For JMS, the status message will be: SOAP Fault

requestLines returned?

Yes

lines returned?

No

soapResponseData

Contains an SOAP fault.

webMethods Integration Server Built-In Services Reference Version 9.6

164

Odd Header
Client Folder

Use Case
The pub.client:soapClient service fails while processing the SOAP response.
Parameter

Description

status

900

statusMessage

Error occurred while processing SOAP request

requestLines returned?

Yes

lines returned?

Yes

soapResponseData

Contains an exception.

When invoking pub.client:soapClient to execute an In-Out operation asynchronously using

SOAP over JMS, keep the following information in mind:
For an asynchronous request/reply, you must pass jms.async= true into the
transportHeaders input parameter.
To instruct Integration Server to write the request message for an asynchronous
request/reply to the client side queue when the JMS provider is not available, the
JMS binder must be congured to use the client side queue. Specically, in the
consumer web service descriptor, the Use CSQ property for the JMS binder must be
set to true.
When pub.client:soapClient sends an asynchronous request it executes to completion
without populating any response headers for the lines output parameter.
Even though pub.client:soapClient does not wait for a SOAP response, it will execute
the response handlers assigned to the consumer web service descriptor. However,
the messageContext that is available to handler services will not contain a response
message. Handler services that do not operate on the response message and instead
perform activities such as clean up following a request handler invocation might still
provide value for an asynchronous request/reply.
If you want to retrieve the SOAP response from the provider, you need to receive
and process the response with a custom solution. This might include using standard
JMS trigger or an on-demand message consumer to receive the message and then
using the pub.soap* services to process the SOAP message.
Note: Using a JMS trigger or message consumer to receive the response bypasses
any response handlers or policies applied to the SOAP response, including
any WS-SecurityPolicy. The SOAP response does not undergo any processing
provided by the response handlers or policies aached to the consumer web service
descriptor. Any response messages that require decryption or authentication will

webMethods Integration Server Built-In Services Reference Version 9.6

165

Even Header
Client Folder

not be usable. Consequently, do not use an asynchronous request/reply to invoke an

In-Out operation to which the WS-SecurityPolicy is applied.
When using pub.client:soapClient to execute a Robust In-only operation using SOAP over
JMS, keep the following information in mind:
For a consumer web service descriptor, Integration Server provides partial support
for Robust In-Only operations with a SOAP over JMS binding. When Integration
Server creates a consumer web service descriptor from a WSDL that contains a
Robust In-Only operation and that operation is dened as part of a portType with
a SOAP over JMS binding, Integration Server populates the reply destination in
the JMS message header (the JMSReplyTo header eld) but otherwise treats the
operation as In-Only.
Specically, pub.client:soapClient will not produce or wait for any output besides the
transportInfo parameter. If an exception occurs while the provider processes the
request, the web service connector does not retrieve or process the SOAP response.
If you want to retrieve a SOAP response (which includes the SOAP fault) that the
provider sends when an exception occurs during web service execution, you need to
receive and process the response with a custom solution. This might include using
a standard JMS trigger or an on-demand message consumer to receive the message
and using the pub.soap* services to process the SOAP message.
Note: Using a JMS trigger or message consumer to receive the response bypasses
any policies applied to the SOAP response and any response handlers assigned
to the consumer web service descriptor. The SOAP response does not undergo
any processing provided by the response handlers or policies aached to the
consumer web service descriptor. Any response messages that require decryption
or authentication will not be usable. Consequently, do not use an asynchronous
request/reply to invoke an In-Out operation to which the WS-SecurityPolicy is
applied.
See Also
pub.client:soapHTTP
pub.client:soapRPC

pub.client:soapHTTP
WmPublic. Deprecated - Submits a SOAP message to a server via HTTP or HTTPS.
Input Parameters
soapRequestData

Object SOAP message that is to be sent. This object must be

produced with the services in the soap folder. See the Usage
Notes for more information.

webMethods Integration Server Built-In Services Reference Version 9.6

166

Odd Header
Client Folder

address

String URL to which you want the SOAP message sent. For
example:
https://servername:5555/soap/default

auth

validateSOAP

Document Optional. Parameters specifying the credentials that

are to be submied to the server specied in address . Each
element is dened as follows:
Key

Description

type

String Type of authentication that the

service will perform. Leave this eld
blank, as the only option currently
available is basic HTTP authentication.

user

String User name that this service will

use if one is requested.

pass

String Password that this service will

submit if one is requested.

String Optional. Indicates whether or not the response message

is to be validated against the SOAP schema. Set to:
true to validate the response message and throw an

exception if the response does not conform to the SOAP

schema.
false to bypass the validation process. This is the default.

SOAPAction

String Optional. Value to which you want to set the

SOAPAction HTTP header.

contentType

String Optional. Species the value of Content-Type in the

HTTP header. Set to:
text/xml; charset="utf-8" to specify the content type

as XML and the character encoding of the message text as

UTF-8. This is the default.

text/xml to specify the content type as XML. Since the

charset parameter is not specied, the character encoding of

the message text defaults to US-ASCII.

loadAs

String Optional. Species the format of the soapResponseData.

Default value is stream for an HTTP service and
byteArrayStream for an HTTPS service. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

167

Even Header
Client Folder

stream to return the body of the response as a

java.io.InputStream. Use this option when you will invoke an

HTTP web service. This is the default for an HTTP service.
bytes to return the body of the response as a byte[ ]. Use

this option if the body will be used as input to a service that

operates on whole HTML or XML documents (for example,
pub.xml:queryXMLNode).
byteArrayStream to have the response stream fully read

and converted to java.io.ByteArrayStream. This prevents

data loss or a truncated SOAP response if the connection
closes prematurely. Use this option when you will invoke an
HTTPS web service. This is the default for an HTTPS service.
timeout

String Optional. Time (measured in milliseconds) to wait for

a response from the remote server before timing out and
terminating the request. The default value is to wait forever.

encoding

String Default character set for encoding SOAP message.

Specify an IANA-registered character set (for example,
ISO-8859-1). The default is UTF-8.
The encoding parameter is used to override the encoding
determined by the wa.server.netEncoding server
conguration parameter. For more information about
wa.server.netEncoding, see webMethods Integration Server
Administrators Guide .

Output Parameters
soapResponseData

Object The SOAP response message returned by the server

specied in address .

header

Document Conditional. Headers from the HTTP response. Will

contain the following keys:
Key

Description

lines

Document Header elds from the HTTP

response. Each key in lines represents a
eld (line) of the response header. Key
names represent the names of header
elds. The keys' values are Strings
containing the values of the elds.

webMethods Integration Server Built-In Services Reference Version 9.6

168

Odd Header
Client Folder

soapStatus

status

String Status code from the HTTP

response.

statusMessage

String Status message from the HTTP

response.

String Flag indicating whether the SOAP request message was

processed successfully.
A value of...

Indicates that...

The remote server successfully

processed the SOAP request and
returned a SOAP response message.

The remote server returned a SOAP

fault, indicating that the SOAP request
was received but was not processed
successfully.

The server returned an error that was

not a SOAP fault. This indicates that
some type of HTTP error occurred
(often, an HTTP 404). You can check the
status element in header to determine
the type of HTTP error that occurred.

Usage Notes
This service is deprecated. There is not a replacement service.
If address begins with https:, you can use pub.security.keystore:setKeyAndChain to specify
the certicate chain. If you do not specify a certicate chain, pub.client:soapHTTP uses the
default outbound SSL certicate seings to authenticate the resources.
To send a SOAP message with this service, you must rst generate an empty SOAP
object with the pub.soap.utils:createSoapData service and then populate it using services such
as pub.soap.utils:addHeaderEntry and pub.soap.utils:addBodyEntry.
See Also
pub.client:soapRPC
Examples
sample.soap:buildMsg_sendHTTP

webMethods Integration Server Built-In Services Reference Version 9.6

169

Even Header
Client Folder

pub.client:soapRPC
WmPublic. Deprecated - Submits a SOAP remote procedure call via HTTP or HTTPS.
Input Parameters
address

String String specifying the numeric address or name of the

server on which the remote procedure resides. If you are
submiing the request to an Integration Server, remember
to direct it to the RPC processor as shown in the following
example:
http://rubicon:5555/soap/rpc

reqParms

method

auth

Document The input parameters that are to be passed to

the remote procedure. For example, if you wanted to pass
three String parameters, acct , amt , and org , containing the
values Cash, 150.00, and Sales, reqParms would contain
the following:
Key

Value

acct

Cash

amt

150.00

org

Sales

Document The QName of the requested procedure where:

Key

Value

namespaceName

String Namespace portion of the

procedure's QName.

localName

String Local portion of the procedure's

QName.

Document Optional. User name and password that are to be

submied to the server specied in address .
Key

Value

webMethods Integration Server Built-In Services Reference Version 9.6

170

Odd Header
Client Folder

type

String Type of authentication that the

service will perform. Leave this eld
blank, as the only option currently
available is basic HTTP authentication.

user

String User name that this service will use

if one is requested.

pass

String Password that this service will

submit if one is requested.

targetInputSignature

String Optional. Fully qualied name of the IS document

type to use to validate and encode the contents of reqParms .

targetOutputSignature

String Optional. Fully qualied name of the IS document

type to use to validate and decode the output value returned
by the remote procedure.

SOAPAction

String Optional. Value to which you want to set the

SOAPAction HTTP header.

contentType

String Optional. Species the value of Content-Type in the

HTTP header. Set to:
text/xml; charset="utf-8" to specify the content type
as XML and the character encoding of the text as UTF-8.
This is the default.
text/xml to specify the content type as XML. Since the
charset parameter is not specied, the character encoding

of the text defaults to US-ASCII.

encoding

String Optional. Species the encoding method. Default

value is UTF-8.

loadAs

String Optional. Species the format of the

soapResponseData. Default value is stream. Set to:
stream to return the body of the response as a
java.io.InputStream. Use this option when you will invoke
an HTTP web service. This is the default.
byteArrayStream to have the response stream fully read
and converted to java.io.ByteArrayStream. This prevents
data loss or a truncated SOAP response if the connection
closes prematurely. Use this option when you will invoke
an HTTPS web service.

webMethods Integration Server Built-In Services Reference Version 9.6

171

Even Header
Client Folder

timeout

String Optional. Time (measured in milliseconds) to wait for

a response from the server hosting the remote procedure
before timing out and terminating the request. The default
value is to wait forever.

Output Parameters
soapResponseData

Object A SOAP object containing the SOAP response

message returned by the server specied in address .

respParms

Document Output parameters returned by the remote

procedure. For example, if the remote procedure returned
two String parameters, status and balance , containing the
values closed and -4.95, respParms would contain the
following:

header

soapStatus

Key

Value

status

closed

balance

-4.95

Document Conditional. Headers from the HTTP response.

Will contain the following keys:
Key

Value

lines

Document Header elds from the HTTP

response. Each key in lines represents a
eld (line) of the response header. Key
names represent the names of header
elds. The keys' values are Strings
containing the values of the elds.

status

String Status code from the HTTP

response.

statusMessage

String Status message from the HTTP

response.

String Flag indicating whether the SOAP request message

was processed successfully.

webMethods Integration Server Built-In Services Reference Version 9.6

172

Odd Header
Client Folder

A value of...

Indicates that...

The remote server successfully processed

the SOAP request and returned a SOAP
response message.

The remote server returned a SOAP

fault, indicating that the SOAP request
was received but was not processed
successfully.

The server returned an error that was not

a SOAP fault. This indicates that some
type of HTTP error occurred (often, an
HTTP 404). You can check the status eld
in header to determine the type of HTTP
error that occurred.

Usage Notes
This service is deprecated. There is not a replacement service.
To disable output validation for pub.client:soapRPC, set the
wa.server.soap.validateResponse server conguration parameter to false. For more
information about wa.server.soap.validateResponse, see webMethods Integration Server
Administrators Guide.
If address begins with https:, you can use pub.security.keystore:setKeyAndChain to specify
the certicate chain. If you do not specify a certicate chain, pub.client:soapRPC uses the
default outbound SSL certicate seings to authenticate the resources.
See Also
pub.client:soapHTTP
Examples
sample.soap:buildRPC_SendHTTPSimple

webMethods Integration Server Built-In Services Reference Version 9.6

173

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

174

Odd Header
Date Folder

4 Date Folder
Pattern String Symbols ..............................................................................................................

176

Time Zones ................................................................................................................................

177

Examples ....................................................................................................................................

179

Notes on Invalid Dates ..............................................................................................................

180

Summary of Elements in this Folder .........................................................................................

180

webMethods Integration Server Built-In Services Reference Version 9.6

175

Even Header
Date Folder

You can use the elements in the date folder to generate and format date values.

Pattern String Symbols

Many of the date services require you to specify paern strings describing the data's
current format and/or the format to which you want it converted. For services that
require a paern string, use the symbols in the following table to describe the format of
your data. For example, to describe a date in the January 15, 1999 format, you would use
the paern string MMMMM dd, yyyy. To describe the format 01/15/99, you would use the
paern string MM/dd/yy. For more information about these paern string symbols, see
the Oracle Java API documentation for the SimpleDateFormat class.
Symbol

Meaning

Presentation

Example

era designator

Text

AD

year

Number

1996 or 96

month in year

Text or Number

July or Jul or 07

day in month

Number

10

hour in am/pm (1-12)

Number

12

hour in day (0-23)

Number

minute in hour

Number

30

second in minute

Number

55

millisecond

Number

978

day in week

Text

Tuesday or Tue

day in year

Number

189

day of week in month

Number

2 (2nd Wed in July)

week in year

Number

27

week in month

Number

webMethods Integration Server Built-In Services Reference Version 9.6

176

Odd Header
Date Folder

Symbol

Meaning

Presentation

Example

am/pm marker

Text

PM

hour in day (1-24)

Number

24

hour in am/pm (0-11)

Number

time zone

Text

Pacific Standard
Time or PST or
GMT-08:00

RFC 822 time zone

(JVM 1.4 or later)

Number

-0800 (offset from

GMT/UT)

'

escape for text

Delimiter

''

single quote

Literal

'

Time Zones
When working with date services, you can specify time zones. The Earth is divided
into 24 standard time zones, one for every 15 degrees of longitude. Using the time
zone including Greenwich, England (known as Greenwich Mean Time, or GMT) as the
starting point, the time is increased by an hour for each time zone east of Greenwich and
decreases by an hour for each time zone west of Greenwich. The time dierence between
a time zone and the time zone including Greenwich, England (GMT) is referred to as the
raw oset.
The following table identies the dierent time zones for the Earth and the raw oset for
each zone from Greenwich, England. The eects of daylight savings time are ignored in
this table.
Note: Greenwich Mean Time (GMT) is also known as Universal Time (UT).
ID

Raw Offset

Name

MIT

-11

Midway Islands Time

HST

-10

Hawaii Standard Time

AST

-9

Alaska Standard Time

webMethods Integration Server Built-In Services Reference Version 9.6

177

Even Header
Date Folder

ID

Raw Offset

Name

PST

-8

Pacic Standard Time

PNT

-7

Phoenix Standard Time

MST

-7

Mountain Standard Time

CST

-6

Central Standard Time

EST

-5

Eastern Standard Time

IET

-5

Indiana Eastern Standard Time

PRT

-4

Puerto Rico and U.S. Virgin Islands Time

CNT

-3.5

Canada Newfoundland Time

AGT

-3

Argentina Standard Time

BET

-3

Brazil Eastern Time

GMT

Greenwich Mean Time

ECT

+1

European Central Time

CAT

+2

Central Africa Time

EET

+2

Eastern European Time

ART

+2

(Arabic) Egypt Standard Time

EAT

+3

Eastern African Time

MET

+3.5

Middle East Time

NET

+4

Near East Time

PLT

+5

Pakistan Lahore Time

IST

+5.5

India Standard Time

BST

+6

Bangladesh Standard Time

webMethods Integration Server Built-In Services Reference Version 9.6

178

Odd Header
Date Folder

ID

Raw Offset

Name

VST

+7

Vietnam Standard Time

CTT

+8

China Taiwan Time

JST

+9

Japan Standard Time

ACT

+9.5

Australian Central Time

AET

+10

Australian Eastern Time

SST

+11

Solomon Standard Time

NST

+12

New Zealand Standard Time

Examples
You can specify timezone input parameters in the following formats:
As a full name. For example:
Asia/Tokyo

America/Los_Angeles

You can use the java.util.TimeZone.getAvailableIDs() method to obtain a list of the valid
full name time zone IDs that your JVM version supports.
As a custom time zone ID, in the format GMT[+ | -]hh[ [:]mm]. For example:
GMT+2:00

All time zones 2 hours east of Greenwich (that is, Central Africa
Time, Eastern European Time, and Egypt Standard Time)

GMT-3:00

All time zones 3 hours west of Greenwich (that is, Argentina

Standard Time and Brazil Eastern Time)

GMT+9:30

All time zones 9.5 hours east of Greenwich (that is, Australian
Central Time)

As a three-leer abbreviation from the table above. For example:

PST

Pacic Standard Time

webMethods Integration Server Built-In Services Reference Version 9.6

179

Even Header
Date Folder

Note: Because some three-leer abbreviations can represent multiple time zones (for
example, "CST" could represent both U.S. "Central Standard Time" and "China Standard
Time"), all abbreviations are deprecated. Use the full name or custom time zone ID
formats instead.

Notes on Invalid Dates

If you use an invalid date with a date service, the date service automatically translates
the date to a legal date. For example, if you specify "1999/02/30" as input, the date
service interprets the date as "1999/03/02" (two days after 2/28/1999).
If you use "00" for the month or day, the date service interprets "00" as the last month or
day in the Gregorian calendar. For example, if you specify "00" for the month, the date
service interprets it as 12.
If the paern yy is used for the year, the date service uses a 50-year moving window
to interpret the value of yy . The date service establishes the window by subtracting 49
years from the current year and adding 50 years to the current year. For example, if you
are running the webMethods Integration Server in the year 2000, the moving window
would be from 1951 to 2050. The date service interprets 2-digit years as falling into this
window (for example, 12 would be 2012, 95 would be 1995).

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.date:calculateDateDifference

WmPublic. Calculates the dierence between

two dates and returns the result as seconds,
minutes, hours, and days.

pub.date:currentNanoTime

WmPublic. Returns the current time

returned by the most precise system timer, in
nanoseconds.

pub.date:dateBuild

WmPublic. Builds a date String using the

specied paern and the specied date
elements.

pub.date:dateTimeBuild

WmPublic. Builds a date/time string using

the specied paern and the specied date
elements.

webMethods Integration Server Built-In Services Reference Version 9.6

180

Odd Header
Date Folder

Element

Package and Description

pub.date:dateTimeFormat

WmPublic. Converts date/time (represented as a

String) string from one format to another.

pub.date:elapsedNanoTime

WmPublic. Calculates the time elapsed

between the current time and the given time, in
nanoseconds.

pub.date:formatDate

WmPublic. Formats a Date object as a string.

pub.date:getCurrentDate

WmPublic. Returns the current date as a Date

object.

pub.date:getCurrentDateString

WmPublic. Returns the current date as a String

in a specied format.

pub.date:getWorkingDays

WmPublic. Returns the number of working

days between two dates.

pub.date:calculateDateDifference
WmPublic. Calculates the dierence between two dates and returns the result as
seconds, minutes, hours, and days.
Input Parameters
startDate

String Starting date and time.

endDate

String Ending date and time.

startDatePaern

String Format in which the startDate parameter is to be

specied (for example, yyyyMMdd HH:mm:ss.SSS). For
paern-string notation, see "Paern String Symbols" on page
176.

endDatePaern

String Format in which the endDate parameter is to be specied

(for example, yyyyMMdd HH:mm:ss.SSS). For paern-string
notation, see "Paern String Symbols" on page 176.

webMethods Integration Server Built-In Services Reference Version 9.6

181

Even Header
Date Folder

Output Parameters
dateDierenceSeconds String The dierence between the startingDateTime and
endingDateTime, truncated to the nearest whole number of
seconds.
dateDierenceMinutes String The dierence between the startingDateTime and
endingDateTime, truncated to the nearest whole number of
minutes.
dateDierenceHours

String The dierence between the startingDateTime and

endingDateTime, truncated to the nearest whole number of
hours.

dateDierenceDays

String The dierence between the startingDateTime and

endingDateTime, truncated to the nearest whole number of
days.

Usage Notes
Each output value represents the same date dierence, but in a dierent scale. Do not
add these values together. Make sure your subsequent ow steps use the correct output,
depending on the scale required.

pub.date:currentNanoTime
WmPublic. Returns the current time returned by the most precise system timer, in
nanoseconds.
Input Parameters
None.
Output Parameters
nanoTime

java.lang.Long Current time returned by the most precise system

timer, in nanoseconds.

pub.date:dateBuild
WmPublic. Builds a date String using the specied paern and the specied date
elements.

webMethods Integration Server Built-In Services Reference Version 9.6

182

Odd Header
Date Folder

Input Parameters
paern

String Paern representing the format in which you want the date
returned. For paern-string notation, see "Paern String Symbols"
on page 176. If you do not specify paern , dateBuild returns null.
If paern contains a time zone and timezone is not specied, the
default time zone of webMethods Integration Server is used.

year

String Optional. The year expressed in yyyy or yy format (for

example, 01 or 2001). If you do not specify year or you specify an
invalid value, dateBuild uses the current year.

month

String Optional. The month expressed as a number (for example,

1 for January, 2 for February). If you do not specify month or you
specify an invalid value, dateBuild uses the current month.

dayofmonth

String Optional. The day of the month expressed as a number (for

example, 1 for the rst day of the month, 2 for the second day of
the month). If you do not specify dayofmonth or you specify an
invalid value, dateBuild uses the current day.

timezone

String Optional. Time zone in which you want the output date and
time expressed. Specify a time zone code as shown in "Time Zones"
on page 177 (for example, EST for Eastern Standard Time).
If you do not specify timezone , the value of the server's "user
timezone" property is used. If this property has not been set, GMT
is used.

locale

String Optional. Locale in which the date is to be expressed. For

example, if locale is en (for English), the paern EEE d MMM yyyy
will produce Friday 23 August 2002, and the locale of fr (for
French) will produce vendredi 23 aot 2002.

Output Parameters
value

String The date specied by year , month , and dayofmonth , in the

format of paern .

pub.date:dateTimeBuild
WmPublic. Builds a date/time string using the specied paern and the specied date
elements.

webMethods Integration Server Built-In Services Reference Version 9.6

183

Even Header
Date Folder

Input Parameters
paern

String Paern representing the format in which you want the time
returned. For paern-string notation, see "Paern String Symbols" on
page 176. If you do not specify paern , dateTimeBuild returns null. If
paern contains a time zone and the timezone parameter is not set, the
time zone of Integration Server is used.

year

String Optional. The year expressed in yyyy or yy format (for

example, 01 or 2001). If you do not specify year or you specify an
invalid value, dateTimeBuild uses the current year.

month

String Optional. The month expressed as a number (for example, 1 for

January, 2 for February). If you do not specify month or you specify
an invalid value, dateTimeBuild uses the current month.

dayofmonth

String Optional. The day of the month expressed as a number (for

example, 1 for the rst day of the month, 2 for the second day of the
month). If you do not specify dayofmonth or you specify an invalid
value, dateTimeBuild uses the current day.

hour

String Optional. The hour expressed as a number based on a 24-hour

clock. For example, specify 0 for midnight, 2 for 2:00 A.M., and 14 for
2:00 P.M. If you do not specify hour or you specify an invalid value,
dateTimeBuild uses 0 as the hour value.

minute

String Optional. Minutes expressed as a number. If you do not specify

minute or you specify an invalid value, dateTimeBuild uses 0 as the
minute value.

second

String Optional. Seconds expressed as a number. If you do not specify

second or you specify an invalid value, dateTimeBuild uses 0 as the
second value.

millis

String Optional. Milliseconds expressed as a number. If you do not

specify millis or you specify an invalid value, dateTimeBuild uses 0 as
the millis value.

timezone

String Optional. Time zone in which you want the output date and
time expressed. Specify a time zone code as shown in "Time Zones"
on page 177 (for example, EST for Eastern Standard Time).
If you do not specify timezone , the value of the server's "user
timezone" property is used. If this property has not been set, GMT is
used.

webMethods Integration Server Built-In Services Reference Version 9.6

184

Odd Header
Date Folder

locale

String Optional. Locale in which the date is to be expressed. For

example, if locale is en (for English), the paern EEE d MMM yyyy will
produce Friday 23 August 2002, and the locale of fr (for French)
will produce vendredi 23 aot 2002.

Output Parameters
value

String Date and time in format of paern .

pub.date:dateTimeFormat
WmPublic. Converts date/time (represented as a String) string from one format to
another.
Input Parameters
inString

String Date/time that you want to convert.

Important: If inString contains a character in the last position, that
character is interpreted as 0. This can result in an inaccurate date.
For information about invalid dates, see "Notes on Invalid Dates" on
page 180.

currentPaern

String Paern string that describes the format of inString . For

paern-string notation, see "Paern String Symbols" on page
176.

newPaern

String Paern string that describes the format in which you want
inString returned. For paern-string syntax, see "Paern String
Symbols" on page 176.

locale

String Optional. Locale in which the date is to be expressed. For

example, if locale is en (for English), the paern EEE d MMM yyyy
will produce Friday 23 August 2002, and the locale of fr (for
French) will produce vendredi 23 aot 2002.

lenient

String Optional. A ag indicating whether Integration Server

throws an exception if the inString value does not adhere to the
format specied in currentPaern parameter. Set to:
true to perform a lenient check. This is the default.

In a lenient check, if the format of the date specied in the

inString parameter does not match the format specied in the

webMethods Integration Server Built-In Services Reference Version 9.6

185

Even Header
Date Folder

currentPaern parameter, Integration Server interprets and

returns the date in the format specied in the currentPaern
parameter. If the interpretation is incorrect, the service will
return an invalid date.
false to perform a strict check.

In a strict check, the Integration Server throws an exception if the

format of the date specied in the inString parameter does not
match the format specied in the currentPaern parameter.
Output Parameters
value

String The date/time given by inString , in the format of

newPaern .

Usage Notes
As described in "Notes on Invalid Dates" on page 180, if the paern yy is
used for the year, dateTimeFormat uses a 50-year moving window to interpret
the value of the year. If you need to change this behavior so that the year is
interpreted as 80 years before or 20 years after the current date (as described in
the Java class java.text.SimpleDateFormat), set the server conguration parameter
wa.server.pubDateTimeFormat.javaSlidingWindow to true. For information about
seing conguration parameters, see webMethods Integration Server Administrators Guide.
By default, the Integration Server throws an exception if no input is passed to the
service. To suppress the error message and return a null value for the value parameter,
set the server conguration parameter wa.server.date.suppressPaernError to true.
For information about seing conguration parameters, see webMethods Integration
Server Administrators Guide.
If currentPaern does not contain a time zone, the value is assumed to be in the time
zone of the webMethods Integration Server.
If newPaern contains a time zone, the time zone of the webMethods Integration Server
is used.

pub.date:elapsedNanoTime
WmPublic. Calculates the time elapsed between the current time and the given time, in
nanoseconds.
Input Parameters
nanoTime

java.lang.Long Time in nanoseconds. If nanoTime is less than

zero, then the service treats it as zero.

webMethods Integration Server Built-In Services Reference Version 9.6

186

Odd Header
Date Folder

Output Parameters
elapsedNanoTime

java.lang.Long The dierence between the current time in

nanoseconds and nanoTime . If nanoTime is greater than the
current nano time, the service returns zero.

elapsedNanoTimeStr

String The dierence between the current time in nanoseconds

and nanoTime . The dierence is expressed as a String, in this
format:
[years] [days] [hours] [minutes] [seconds] [millisec] [microsec]
<nanosec>
If nanoTime is greater than the current nano time, the service
returns zero.

pub.date:formatDate
WmPublic. Formats a Date object as a string.
Input Parameters
date

java.util.Date Optional. Date/time that you want to convert.

paern

String Paern string that describes the format in which you want
the date returned. For paern-string notation, see "Paern String
Symbols" on page 176.

timezone

String Optional. Time zone in which you want the output date and
time expressed. Specify a time zone code as shown in "Time Zones"
on page 177 (for example, EST for Eastern Standard Time).
If you do not specify timezone , the value of the server's "user
timezone" property is used. If this property has not been set, GMT is
used.

locale

String Optional. Locale in which the date is to be expressed. For

example, if locale is en (for English), the paern EEE d MMM yyyy
will produce Friday 23 August 2002, and the locale of fr (for
French) will produce vendredi 23 aot 2002.

webMethods Integration Server Built-In Services Reference Version 9.6

187

Even Header
Date Folder

Output Parameters
value

String The date/time given by date in the format specied by paern.

pub.date:getCurrentDate
WmPublic. Returns the current date as a Date object.
Input Parameters
None.
Output Parameters
date

java.util.Date Current date.

pub.date:getCurrentDateString
WmPublic. Returns the current date as a String in a specied format.
Input Parameters
paern

String Paern representing the format in which you want the date
returned. For paern-string notation, see "Paern String Symbols"
on page 176.

timezone

String Optional. Time zone in which you want the output date and
time expressed. Specify a time zone code as shown in "Time Zones"
on page 177 (for example, EST for Eastern Standard Time).
If you do not specify timezone , the value of the server's "user
timezone" property is used. If this property has not been set, GMT
is used.

locale

String Optional. Locale in which the date is to be expressed. For

example, if locale is en (for English), the paern EEE d MMM yyyy
will produce Friday 23 August 2002, and the locale of fr (for
French) will produce vendredi 23 aot 2002.

webMethods Integration Server Built-In Services Reference Version 9.6

188

Odd Header
Date Folder

Output Parameters
value

String Current date in the format specied by paern .

pub.date:getWorkingDays
WmPublic. Returns the number of working days between two dates.
The number of working days returned includes the startDate, but excludes the endDate.
Input Parameters
startDate

String Starting date and time.

endDate

String Ending date and time.

startDatePaern

String Format in which the startDate parameter is to be specied

(for example, yyyyMMdd HH:mm:ss.SSS). For paern-string
notation, see "Paern String Symbols" on page 176.

endDatePaern

String Format in which the endDate parameter is to be specied

(for example, yyyyMMdd HH:mm:ss.SSS). For paern-string
notation, see "Paern String Symbols" on page 176.

Output Parameters
workingDays

String Number of days between startDate and endDate excluding

weekends and holidays.

Usage Notes
The pub.date:getWorkingDays service requires you to congure holidays and weekend
days in the holidays.cnf conguration le in Integration Server_directory\instances
\instance_name \packages\WmPublic\cong directory. The pub.date:getWorkingDays
service uses this conguration le to nd the number of working days between two
dates.
Note: If you make any changes to the holidays.cnf, you must reload the WmPublic
package or restart Integration Server for the changes to take eect.
Parameter Settings for holidays.cnf file
The following table gives the parameter seings for the holidays.cnf le:

webMethods Integration Server Built-In Services Reference Version 9.6

189

Even Header
Date Folder

Parameter

Description

holiday.format

The date format in which holidays are to be specied. The

default format is MM/dd/yyyy.

holiday.<number>

Holidays in a year. No default values are set for the holiday

parameter in the holidays.cnf le.
For example, if July 4, 2009 and December 25, 2009 are
holidays, then it can be specied as:
holiday.1=07/04/2009
holiday.2=12/25/2009

weekend.<number>

Weekends days. Valid values are sunday, monday, tuesday,

wednesday, thursday, friday, and saturday. No default
values are set for the weekend parameter in the holidays.cnf
le.
If Sunday and Saturday are weekends, then it can be
specied as:
weekend.1
weekend.2=saturday

Note: If invalid date or weekend is specied in the conguration le, the

pub.date:getWorkingDays service will throw errors on execution.

webMethods Integration Server Built-In Services Reference Version 9.6

190

Odd Header
Db Folder

5 Db Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

192

191

Even Header
Db Folder

You use the elements in the db folder to access JDBC-enabled databases.

Note: The webMethods Adapter for JDBC also provides services that perform operations
against JDBC-enabled databases. See the webMethods Adapter for JDBC Installation and
Users Guide for information.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.db:call

WmDB. Invokes a stored procedure on a target database.

As an alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:clearTransaction

WmDB. Clears the transactional state within a database

connection. As an alternative to this service, consider using
the services provided with the webMethods Adapter for
JDBC.

pub.db:close

WmDB. Closes a specied database connection. As an

alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:closeAll

WmDB. Closes all database connections that the session has

opened. As an alternative to this service, consider using the
services provided with the webMethods Adapter for JDBC.

pub.db:commit

WmDB. Commits changes to a database. As an alternative

to this service, consider using the services provided with the
webMethods Adapter for JDBC.

pub.db:connect

WmDB. Creates a connection to the database using the

supplied JDBC URL, user name, and password. As an
alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:delete

WmDB. Removes all rows in the specied table that meet

the given criteria. As an alternative to this service, consider
using the services provided with the webMethods Adapter
for JDBC.

webMethods Integration Server Built-In Services Reference Version 9.6

192

Odd Header
Db Folder

Element

Package and Description

pub.db:execSQL

WmDB. Executes the specied SQL statement. As an

alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:getProcInfo

WmDB. Retrieves information about one or more stored

procedures. As an alternative to this service, consider using
the services provided with the webMethods Adapter for
JDBC.

pub.db:getProcs

WmDB. Retrieves the names of stored procedures for the

specied database. As an alternative to this service, consider
using the services provided with the webMethods Adapter
for JDBC.

pub.db:getTableInfo

WmDB. Retrieves information about columns in the

specied table. As an alternative to this service, consider
using the services provided with the webMethods Adapter
for JDBC.

pub.db:getTables

WmDB. Retrieves the names of tables in the specied

database and schema. As an alternative to this service,
consider using the services provided with the webMethods
Adapter for JDBC.

pub.db:insert

WmDB. Inserts one or more rows into the specied table.

As an alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:query

WmDB. Retrieves all rows from the specied table that meet
the given criteria. As an alternative to this service, consider
using the services provided with the webMethods Adapter
for JDBC.

pub.db:rollback

WmDB. Discards changes to a database. As an alternative to

this service, consider using the services provided with the
webMethods Adapter for JDBC.

pub.db:startTransaction

WmDB. Begins a transaction on a database connection. As

an alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:update

WmDB. Updates all rows in a table that meet the given

criteria. Rows are updated with the supplied new data. As

webMethods Integration Server Built-In Services Reference Version 9.6

193

Even Header
Db Folder

Element

Package and Description

an alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

pub.db:call
WmDB. Invokes a stored procedure on a target database. As an alternative to this
service, consider using the services provided with the webMethods Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Alias of the database on which you want to

execute the stored procedure.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user specied in $dbUser .

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog. Include

this parameter if your DBMS supports distributed databases
and you want to invoke a stored procedure from a database
other than the one to which you are connected.
If you are not using a distributed database system, you do not
need to specify this parameter.
If you are running against DB2, use this parameter to specify
the stored procedure's location.

webMethods Integration Server Built-In Services Reference Version 9.6

194

Odd Header
Db Folder

$dbSchemaPaern

String Optional. Name of the schema to which the stored

procedure belongs.
If your database supports paern-matching on schemas, you
may specify the schema name with a paern-matching string,
where _ represents a single character and % represents any
string of characters. For example, the value of HR% would
represent any schema beginning with characters HR.
If you are running against DB2, you use this parameter to
specify the stored procedure's AuthID.

$dbProc

String The name of the stored procedure you want to invoke.

$dbProcSig

Document List Optional. Set of parameters containing

information about the stored procedure you want to invoke.
Key

Description

name

String Parameter name dened in the stored

procedure.

sqlType

String Type of procedure parameter for name

as dened in the database. Set to one of the
following values:
BIT
TINYINT
SMALLINT
INTEGER
BiGINT
FLOAT
REAL
DOUBLE
NUMBERIC
DECIMAL
CHAR
VARCHAR
LONGVARCHAR
DATE
TIME
TIMESTAMP
BINARY
VARBINARY
LONGVARBINARY
NULL

direction

String Way in which the parameter is used

by the stored procedure. Set to one of the
following values:
in
out
inout
return value

$dbParamsByOrder

String Optional. Indicates whether the contents of $data should

be sent to the database in order. Set to:
true to send the contents of $data to the database in the order

they are listed in $data .

webMethods Integration Server Built-In Services Reference Version 9.6

195

Even Header
Db Folder

false to send the contents of $data to the database in no

particular order. This is the default.

$data

Document Parameter values for the stored procedure.

Whether the $data parameter is mandatory or not depends
on the wa.server.jdbc.sp.mandateParams property. If
this property is set to false, the $data input parameter
is optional. If this property is true, you must provide
values for the $data parameter. The default value for the
wa.server.jdbc.sp.mandateParams property is true.

Output Parameters
$dbMessage

String Conditional. Message indicating the success or failure of

the operation.

Usage Notes
The output will also contain output parameters and procedure return values (the return
value is called RETURN_VALUE).

pub.db:clearTransaction
WmDB. Clears the transactional state within a database connection. As an alternative
to this service, consider using the services provided with the webMethods Adapter for
JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Alias of the database connection on which

you want to clear the transactional state. The alias is passed
automatically if the database is connected.

$dbURL

String Optional. JDBC URL that identies the database

resource.

webMethods Integration Server Built-In Services Reference Version 9.6

196

Odd Header
Db Folder

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

Output Parameters
$dbMessage

String A message indicating the success or failure of the

operation.

Usage Notes
On some databases, exceptional conditions within transactions will automatically abort
the entire transaction. When this happens, the standard commit/rollback operations are
meaningless because there is no current transaction. If this occurs, use the clearTransaction
service to clear the transactional state and prepare for a new transaction. You should
only use this service if you have begun a transaction and cannot end it with a standard
commit or rollback.
The clearTransaction service does not involve a database operation; it is entirely internal to
the webMethods Integration Server.

pub.db:close
WmDB. Closes a specied database connection. As an alternative to this service,
consider using the services provided with the webMethods Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

webMethods Integration Server Built-In Services Reference Version 9.6

197

Even Header
Db Folder

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$closeDbConnection

String Optional. Indicates whether to remove the database

connection from the pool or return it to the pool for future use.
Set to:
true to close the connection and remove it from the pool.
false to close the connection and return it to the pool for

future use. This is the default.

Output Parameters
$dbMessage

String Message indicating the success or failure of the

operation.

pub.db:closeAll
WmDB. Closes all database connections that the session has opened. As an alternative
to this service, consider using the services provided with the webMethods Adapter for
JDBC.
Input Parameters
None.
Output Parameters
$dbMessage

String Message indicating the success or failure of the

operation.

pub.db:commit
WmDB. Commits changes to a database. As an alternative to this service, consider using
the services provided with the webMethods Adapter for JDBC.

webMethods Integration Server Built-In Services Reference Version 9.6

198

Odd Header
Db Folder

Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Alias of the database on which you want

to commit changes. The alias is passed automatically if the
database is connected.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

Output Parameters
$dbMessage

String Message indicating the success or failure of the

operation.

Usage Notes
This service returns an exception if an error occurs when commiing changes to the
database. The most common reason for this error is that no transaction has been started
(see "pub.db:startTransaction" on page 217).

pub.db:connect
WmDB. Creates a connection to the database using the supplied JDBC URL, user name,
and password. As an alternative to this service, consider using the services provided
with the webMethods Adapter for JDBC.
You can also specify a JDBC driver specic to the database.

webMethods Integration Server Built-In Services Reference Version 9.6

199

Even Header
Db Folder

Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbURL, $dbDriver, $dbProperties
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbProperties

Document Optional. Set of connection parameters that are to be

used to make the database connection. Within $dbProperties ,
key names represent the names of the connection parameters
that are to be used to establish the connection, and the value of
a key species the value of that particular parameter.
In most cases, you will include the keys user and password
in $dbProperties to specify the user name and password
parameters that are to be used to connect to the database. You
may include additional parameters as needed.
The following example shows how $dbProperties would look
if you wanted to set the weblogic.codeset parameter to GBK in
order to extract Unicode data out of the database:
Key

Value

user

dbu

password

dbu

weblogic.codeset

GBK

webMethods Integration Server Built-In Services Reference Version 9.6

200

Odd Header
Db Folder

Output Parameters
$dbConnection

com.wm.app.b2b.server.DBConnection Connection object.

$dbMessage

String Message indicating the success or failure of the

operation.

Usage Notes
Database connections opened by pub.db:connect are associated with the current session.
Multiple aempts to connect to the same database by the same client will result in
the same connection being reused. This means that if client A and client B request
connections to the same database, they each get their own new connection. If client
A makes another call to pub.db:connect, the previous connection is reused. Associating
the database connection with the client session prevents remote clients from having to
reconnect repeatedly to a target database.
Connections are not pooled or shared across sessions. Unless explicitly closed (by calling
pub.db:close or pub.db:closeAll), connections associated with a session are closed when
the session is ushed from memory. This happens at a regular interval, which can be
congured using the Integration Server Administrator. For more information about
seing the session time-out limit, see webMethods Integration Server Administrators Guide.

pub.db:delete
WmDB. Removes all rows in the specied table that meet the given criteria. As an
alternative to this service, consider using the services provided with the webMethods
Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

webMethods Integration Server Built-In Services Reference Version 9.6

201

Even Header
Db Folder

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to delete rows from a table that is not
in the database to which you are connected.
If you are not using a distributed database system or if you
want to delete rows from the database to which you are
connected, you do not need to specify this parameter.
If you are running against DB2, use this parameter to specify
the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

$dbTable

String Name of the table to remove rows from.

$data

Document Optional. Criteria that the rows to delete must meet.

Important: If no criteria are provided, all rows are deleted from the
table.

Output Parameters
$updateCount

String Number of rows deleted.

$dbMessage

String Conditional. Message indicating the success or failure of

the operation.

webMethods Integration Server Built-In Services Reference Version 9.6

202

Odd Header
Db Folder

pub.db:execSQL
WmDB. Executes the specied SQL statement. As an alternative to this service, consider
using the services provided with the webMethods Adapter for JDBC.
The service does not perform any parsing on the SQL statement.
Input Parameters
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog. Include

this parameter if your DBMS supports distributed databases
and you want to retrieve information from a database to which
you are not currently connected.
If you are not using a distributed database system, you do not
need to specify this parameter.
If you are running against DB2, use this parameter to specify
the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

webMethods Integration Server Built-In Services Reference Version 9.6

203

Even Header
Db Folder

$dbSQL

String SQL statement to execute.

$dbProcessEsc

String Optional. Flag that indicates whether JDBC SQL escapes

will be processed. These escapes allow database-independent
access to database-dependent functionality. For example,
dierent dialects of SQL have dierent syntax for date literals.
Using a JDBC escape, you can encode a date literal in a SQL
string that should work on any database. Documentation on
JDBC SQL escapes is widely available.
Set to:
true to process JDBC SQL escapes. This is the default.
false to skip processing JDBC SQL escapes.

$dbProcessReporterTokens
String Optional. Flag that indicates whether reporter tags
(for example, %value xxx%) will be processed in the
SQL. Including these tokens in your SQL allows dynamic
construction of complex SQL statements, at the possible
expense of some execution speed.
Set to:
true to process tags.
false to ignore tags. This is the default.

$dbParamValues

Object List Optional. If the "?" parameters in the SQL statement

are not supplied indirectly (with the $dbParamNames
parameter), they can be supplied directly via this parameter.
See "Usage Notes" on page 205 below. Objects in
$dbParamValues can be of any type.

$dbParamNames

String List Optional. Names of any "?" parameters in the SQL.

See "Usage Notes" on page 205 below.

$dbParamTypes

String List Optional. SQL type names for each parameter.

Use type names from the JDBC 1.2 specication ("INTEGER",
"VARCHAR", etc.).

Output Parameters
sql

String Conditional. SQL as it was actually passed to the target

database. This can be helpful in debugging calls to this service
when dynamic SQL is used (that is, you are using either JDBC
SQL escapes or webMethods Reporter tokens in your SQL).

webMethods Integration Server Built-In Services Reference Version 9.6

204

Odd Header
Db Folder

paramsAsStrings

String List Conditional. Values used for each of the parameters

in the SQL statement. This can be helpful in debugging calls to
this service when "?" parameters are being used.

$rowCount

String Conditional. Number of rows in results.

results

com.wm.util.Table Conditional. Results from the SQL statement.

The Integration Server recognizes and treats this parameter as
a Document List at run time.

$updateCount

String Conditional. Number of rows updated.

$dbMessage

String Conditional. Message indicating the success or failure of

the operation.

Usage Notes
This service does not support updates from a web browser or HTML form.
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
SQL supports host variables ("?") in statements to be executed. Because the pipeline is
based on named values and individual host variables are not named, $dbParamNames
and $dbParamTypes are used to supply an index-to-name mapping for each SQL
statement executed. For example, consider the following SQL query:
SELECT * FROM royalties WHERE pub_id = ? and roy_amt > ?

To execute this SQL query, you could supply the following values to the pub.db:execSQL
service:
Key

Value

Description

$dbSQL

SELECT * FROM
royalties WHERE
pub_id = ? and
roy_amt > ?

SQL query to execute.

$dbParamNames

pub_id
roy_amt

$dbParamTypes

varchar
integer

webMethods Integration Server Built-In Services Reference Version 9.6

Pipeline items to use for

the host variables.
SQL types for the host
variables.

205

Even Header
Db Folder

Key

Value

Description

pub_id

P1053

Values for the host

variables.

roy_amt

10

Values for the host

variables.

Note: Even if there is only one host variable in the SQL

statement, both $dbParamNames and $dbParamTypes are
String arrays.
Example: Consider the following SQL query, which contains an INSERT with three host
variables:
INSERT INTO books VALUES (?, ?, ?)

To execute this SQL query, you could supply the following values to the pub.db:execSQL
service:
Key

Value

Description

$dbSQL

INSERT INTO books

VALUES (?, ?, ?)

SQL query to execute.

$dbParamNames

book_id
pub_id
book_title

Pipeline items to use for

the host variables.

$dbParamTypes

varchar
varchar
varchar

SQL types for the host

variables.

book_id

B234

Values for the host

variables.

pub_id

P1053

Values for the host

variables.

book_title

The Importance of
Being Earnest

Values for the host

variables.

Note: The SQL type names used in the examples are

dened in the java.sql.Types and SQL92. Even if you
used an Oracle database, which calls long string types
"varchar2," you would call them varchar. The standard

webMethods Integration Server Built-In Services Reference Version 9.6

206

Odd Header
Db Folder

Key

Value

Description

names from SQL92 will be mapped into database-specic

type names.

pub.db:getProcInfo
WmDB. Retrieves information about one or more stored procedures. As an alternative
to this service, consider using the services provided with the webMethods Adapter for
JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to retrieve information about a
stored procedure that is not in the database to which you are
currently connected.
If you are not using a distributed database system, you do not
need to specify this parameter.
If you are running against DB2, use this parameter to specify
the stored procedure's location.

webMethods Integration Server Built-In Services Reference Version 9.6

207

Even Header
Db Folder

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the stored procedure's AuthID.

$dbProc

String Name of the procedure about which you want

information.

Output Parameters
This service returns one document (IData object) for each item in the stored procedure's
signature that matches the specied input criteria. Each document contains information
about the signature item. The document's key will be the same as the signature
item's name. For a description of what information is supplied by your database,
seejava.sql.DatabaseMetaData.getProcedureColumns in your JDBC documentation.

pub.db:getProcs
WmDB. Retrieves the names of stored procedures for the specied database. As an
alternative to this service, consider using the services provided with the webMethods
Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

webMethods Integration Server Built-In Services Reference Version 9.6

208

Odd Header
Db Folder

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection

object returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to retrieve a list of stored procedures
from a database other than the one to which you are
connected.
If you are not using a distributed database system, you do not
need to specify this parameter.
If you are running against DB2, use this parameter to specify
the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the stored

procedures belong.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the database's AuthID.

$dbProcNamePaern

String Optional. Paern-matching string that species the

procedures that you want included in the returned list, where
_ represents a single character and % represents any string of
characters. For example, the value DATE% would represent any
procedure beginning with the characters DATE.

Output Parameters
This service returns one document (IData object) for each stored procedure that
matches the specied input criteria. Each document contains information about
a stored procedure. The document's key will be the same as the stored procedure
name. For a description of what information is supplied by your database, see
java.sql.DatabaseMetaData.getProcedures in your JDBC documentation.

webMethods Integration Server Built-In Services Reference Version 9.6

209

Even Header
Db Folder

pub.db:getTableInfo
WmDB. Retrieves information about columns in the specied table. As an alternative
to this service, consider using the services provided with the webMethods Adapter for
JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection

object returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want information about a table that is
not in the database to which you are connected.
If you are not using a distributed database system or
you want information about a table in the database to
which you are connected, you do not need to specify this
parameter.
If you are running against DB2, use this parameter to
specify the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.

webMethods Integration Server Built-In Services Reference Version 9.6

210

Odd Header
Db Folder

If your database supports paern-matching on schemas,

you may specify a paern-matching string for the schema
name, where _ represents a single character and %
represents any string of characters. For example, the value
HR% would represent any schema beginning with the
characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.
$dbTable

String Name of table whose column names you want to

retrieve.

$dbColumnNamePaern

String Optional. Paern-matching string that species

the column names that you want to retrieve, where _
represents a single character and % represents any string of
characters. For example, the value ADDR% would represent
any column name beginning with the characters ADDR.

Output Parameters
This service returns one document (IData object) for each column that matches the
specied input criteria. Each document contains information about a column. The
document's key will be the same as the column name.
Usage Notes
This service accepts input from a web browser or HTML form.

pub.db:getTables
WmDB. Retrieves the names of tables in the specied database and schema. As an
alternative to this service, consider using the services provided with the webMethods
Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

webMethods Integration Server Built-In Services Reference Version 9.6

211

Even Header
Db Folder

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection

object returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want information from a database that is
not the one to which you are connected.
If you are not using a distributed database system or you
want information about the database to which you are
connected, you do not need to specify this parameter.
If you are running against DB2, use this parameter to
specify the database location.

$dbSchemaPaern

String Optional. Name of the schema for which you want the
names of tables.
If your database supports paern-matching on schemas,
you may specify a paern-matching string for the schema
name, where _ represents a single character and %
represents any string of characters. For example, the value
HR% would represent any schema beginning with the
characters HR.
If you want the table names from all schemas, set
$dbSchemaPaern to null.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

$dbTableNamePaern

String Optional. Paern string describing the tables whose

names you want to retrieve.
If your database supports paern-matching on schemas,
you may specify a paern-matching string, where _
represents a single character and % represents any string of
characters. For example, the value HR% would represent any
table name beginning with the characters HR.

webMethods Integration Server Built-In Services Reference Version 9.6

212

Odd Header
Db Folder

If you want all table names, set $dbTableNamePaern to null.

$dbTableTypeList

String List Optional. Set of parameters specifying the types

of tables whose names you want to retrieve. Common JDBC
table types include: TABLE, VIEW, SYSTEM TABLE, ALIAS,
and SYNONYM. Check your driver documentation for others.

Output Parameters
This service returns one document (IData object) for each table that matches the
specied input criteria. Each document contains information about a table. The
document's key will be the same as the table name.
Usage Notes
This service accepts input from a web browser or HTML form.

pub.db:insert
WmDB. Inserts one or more rows into the specied table. As an alternative to this
service, consider using the services provided with the webMethods Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

webMethods Integration Server Built-In Services Reference Version 9.6

213

Even Header
Db Folder

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to insert rows into a table that is not
in the database to which you are connected.
If you are not using a distributed database system or if
you want to insert rows into the database to which you are
connected, you do not need to specify this parameter.
If you are running against DB2, use this parameter to specify
the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

$dbTable

String Name of table in which you want to insert rows.

$dbRollbackOnFail

String Optional. Flag that determine whether changes are

commied if a failure occurs while processing multiple inserts.
Set to:
true to undo changes on failure.
false to commit changes on failure. This is the default.

$data

Document or Document List Optional. Data to insert.

Output Parameters
$updateCount

String Number of rows the service inserted.

$failCount

String Number of rows the service failed to insert.

$errors

Document Conditional. Error messages generated during

service execution.

$dbMessage

String Conditional. Message indicating the success or failure of

the operation.

webMethods Integration Server Built-In Services Reference Version 9.6

214

Odd Header
Db Folder

Usage Notes
This service accepts input from a web browser or HTML form.

pub.db:query
WmDB. Retrieves all rows from the specied table that meet the given criteria. As an
alternative to this service, consider using the services provided with the webMethods
Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to query a table that is not in the
database to which you are connected.
If you are not using a distributed database system or if
you want to query a table in the database to which you are
connected, you do not need to specify this parameter.
If you are running against DB2, use this parameter to specify
the database location.

webMethods Integration Server Built-In Services Reference Version 9.6

215

Even Header
Db Folder

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

$dbTable

String Name of table to query.

$data

Document Optional. Criteria that the rows to retrieve must

meet.

Output Parameters
results

com.wm.util.Table Conditional. Results of the query. The

Integration Server recognizes and treats this parameter as a
Document List at run time.

$dbMessage

String Conditional. Message indicating the success or failure of

an operation.

$rowCount

String Conditional. Number of rows for the table that meet the
criteria specied in $data .

Usage Notes
This service accepts input from a web browser or HTML form.

pub.db:rollback
WmDB. Discards changes to a database. As an alternative to this service, consider using
the services provided with the webMethods Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver

webMethods Integration Server Built-In Services Reference Version 9.6

216

Odd Header
Db Folder

$dbConnection
$dbAlias

String Optional. Alias of the database for which you want to

discard changes. This information is passed automatically.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

Output Parameters
$dbMessage

String Message indicating the success or failure of the

operation.

Usage Notes
This service throws an exception if an error occurs when discarding changes to the
database. The most common reason for this error is that no transaction has been started
(see pub.db:startTransaction).

pub.db:startTransaction
WmDB. Begins a transaction on a database connection. As an alternative to this service,
consider using the services provided with the webMethods Adapter for JDBC.
Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection

webMethods Integration Server Built-In Services Reference Version 9.6

217

Even Header
Db Folder

$dbAlias

String Optional. Alias of the database for which you want to

start the transaction. This information is passed automatically.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

Output Parameters
$dbMessage

String Message indicating the success or failure of the

operation.

Usage Notes
By default, all database connections are opened in "auto commit" mode, meaning
the results of a operation are automatically commied to the database when that
operation succeeds. To use a connection in a transactional context, you must rst call
pub.db:startTransaction to take that connection out of "auto commit" mode.
This service returns an exception if an error occurs when starting the new transaction.
Common reasons for an error when starting a new transaction are:
A transaction is already in progress (see pub.db:commit, pub.db:rollback, or
pub.db:clearTransaction).
The target database does not support transactions.
After a transaction has been started, it must be terminated with a call to either
pub.db:commit (to save all changes to the database) or pub.db:rollback (to discard changes).

pub.db:update
WmDB. Updates all rows in a table that meet the given criteria. Rows are updated with
the supplied new data. As an alternative to this service, consider using the services
provided with the webMethods Adapter for JDBC.

webMethods Integration Server Built-In Services Reference Version 9.6

218

Odd Header
Db Folder

Input Parameters
You may specify the connection parameters in one of the following ways:
$dbAlias
$dbURL, $dbUser, $dbPass, $dbDriver
$dbConnection
$dbAlias

String Optional. Database alias.

$dbURL

String Optional. JDBC URL that identies the database

resource.

$dbUser

String Optional. User name to use to log into the database.

$dbPass

String Optional. Password for the user.

$dbDriver

String Optional. Name of the JDBC driver to use.

$dbConnection

com.wm.app.b2b.server.DBConnection Optional. Connection object

returned by pub.db:connect.

$dbCatalog

String Optional. Name of the database's system catalog.

Include this parameter if your DBMS supports distributed
databases and you want to update rows in a table that is not in
the database to which you are connected.
If you are not using a distributed database system or if
you want to update rows in the database to which you are
connected, you do not need to specify this parameter.
If you are running against DB2, you use this parameter to
specify the database location.

$dbSchemaPaern

String Optional. Name of the schema to which the table

belongs.
If your database supports paern-matching on schemas,
you may specify the schema name with a paern-matching
string, where _ represents a single character and % represents
any string of characters. For example, the value HR% would
represent any schema beginning with the characters HR.
If you are running against DB2, you use this parameter to
specify the table's AuthID.

webMethods Integration Server Built-In Services Reference Version 9.6

219

Even Header
Db Folder

$dbTable

String Name of table to update.

$criteria

Document Criteria that the rows to update must meet.

Important: If no criteria are provided, all rows are updated.

$set

Document New data with which to update rows.

Output Parameters
$updateCount

String Number of rows updated.

$dbMessage

String Conditional. Message indicating the operation failed.

webMethods Integration Server Built-In Services Reference Version 9.6

220

Odd Header
Document Folder

6 Document Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

222

221

Even Header
Document Folder

You use the elements in the document folder to perform operations on documents in the
pipeline.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.document:bytesToDocument

WmPublic. Converts an array of bytes to a

document.

pub.document:deleteDocuments

WmPublic. Deletes the specied documents

from a set of documents.

pub.document:documentListToDocument

WmPublic. Constructs a document (an IData

object) from a document list (an IData[ ]) by
generating key/value pairs from the values
of two elements that you specify in the
document list.

pub.document:documentToBytes

WmPublic. Converts a document to an array

of bytes.

pub.document:documentToDocumentList

WmPublic. Expands the contents of a

document into a list of documents.

pub.document:documentToXMLValues

WmPublic. Converts a document (IData

object) to a String by encoding it in the
webMethods XMLValues format.

pub.document:groupDocuments

WmPublic. Groups a set of documents based

on specied criteria.

pub.document:insertDocument

WmPublic. Inserts a new document in a set of

documents at a specied position.

pub.document:searchDocuments

WmPublic. Searches a set of documents for

entries matching a set of Criteria.

pub.document:sortDocuments

WmPublic. Sorts a set of input documents

based on the specied sortCriteria.

webMethods Integration Server Built-In Services Reference Version 9.6

222

Odd Header
Document Folder

Element

Package and Description

pub.document:XMLValuesToDocument

WmPublic. Decodes a String containing an

XMLValues-encoded document and produces
a document (IData object).

pub.document:bytesToDocument
WmPublic. Converts an array of bytes to a document. This service can only be used with
byte arrays created by executing the pub.document:documentToBytesservice.
Input Parameters
documentBytes

Object An array of bytes (byte[]) to convert to a document.

If documentBytes is null, the service does not return a document
or an error message.
If documentBytes is not a byte array, the service throws a service
exception.
If documentBytes is zero-length, the service produces an empty
document.

Output Parameters
document

Document A document.

Usage Notes
Use this service with the pub.document:documentToBytes service, which converts a document
into a byte array. You can pass the resulting byte array to the pub.document:bytesToDocument
service to convert it back into the original document.
In order for the document-to-bytes-to-document conversion to work, the entire content
of the document must be serializable. Every object in the document must be of a data
type known to Integration Server, or it must support the java.io.Serializable interface.
Note: If Integration Server encounters an unknown object in the document that does
not support the java.io.Serializable interface, that object's value will be lost. It will be
replaced with a string containing the object's class name.

webMethods Integration Server Built-In Services Reference Version 9.6

223

Even Header
Document Folder

pub.document:deleteDocuments
WmPublic. Deletes the specied documents from a set of documents.
Input Parameters
documents

Document List Set of documents that contain the documents you

want to delete.

indices

String List Index values of documents to be deleted from the

documents parameter document list.

Output Parameters
documents

Document List List of documents whose indices do not match the

values in indices parameter.

deletedDocuments

Document List List of deleted documents.

Usage Notes
The pub.document:deleteDocuments service returns an error if the indices parameter value is
less than zero or more than the number of documents in the documents input parameter.

pub.document:documentListToDocument
WmPublic. Constructs a document (an IData object) from a document list (an IData[ ])
by generating key/value pairs from the values of two elements that you specify in the
document list.
Input Parameters
documentList

Document List Set of documents (IData[ ]) that you want to transform

into a single document (IData object).
Note: If the documentList parameter contains a single document instead
of a Document List, the documentListToDocument service does nothing.

name

String Name of the element in the documentList parameter whose

value provides the name of each key in the resulting document.

webMethods Integration Server Built-In Services Reference Version 9.6

224

Odd Header
Document Folder

Important: The data type of the element that you specify in the name
parameter must be String.
value

String Name of the element in the documentList parameter whose

values will be assigned to the keys specied in name . This element
can be of any data type.

Output Parameters
document

Document Document (IData object) containing the key/value pairs

generated from the documentList parameter.

Usage Notes
The following example illustrates how the documentListToDocument service would convert
a document list that contains three documents to a single document containing three
key/value pairs. When you use the documentListToDocument service, you specify which
two elements from the source list are to be transformed into the keys and values in the
output document. In the following example, the values from the pName elements in the
source list are transformed into key names, and the values from the pValue elements are
transformed into the values for these keys.
A documentList containing these three documents:
Key

Value

pName

cx_timeout

pValue

1000

Key

Value

pName

cx_max

pValue

2500

Key

Value

pName

cx_min

pValue

10

webMethods Integration Server Built-In Services Reference Version 9.6

225

Even Header
Document Folder

Would be converted to a document containing these three key:

Key

Value

cx_timeout

1000

cx_max

2500

cx_min

10

pub.document:documentToBytes
WmPublic. Converts a document to an array of bytes.
Input Parameters
document

Document Document (IData object) to convert to bytes.

If document is null, the service does not return an output or an
error message.
If document is not a document (IData), the service throws a service
exception.
If document contains no elements, the service produces a zerolength byte array.

Output Parameters
documentBytes

Object A serialized representation of the document as an array of

bytes (byte[]).

Usage Notes
Use the pub.document:documentToBytes service with the pub.document:bytesToDocument service,
which converts the byte array created by this service back into the original document.
The pub.document:documentToBytes service is useful when you want to write a document to
a le (using the pub.file:bytesToFile service), an input stream (using the pub.io:bytesToStream
service), or a cache (using the pub.cache:put service).
In order for the document-to-bytes-to-document conversion to work, the entire content
of the document must be serializable. Every object in the document must be of a data
type known to Integration Server, or it must support the java.io.Serializable interface. If
Integration Server encounters an unknown object in the document that does not support

webMethods Integration Server Built-In Services Reference Version 9.6

226

Odd Header
Document Folder

the java.io.Serializable interface, that object's value will be lost. Integration Server will
replace it with a string containing the object's class name.
Example
This example describes how to use the pub.document:documentToBytes and
pub.document:bytesToDocument services to cache a document in the pipeline.
1. A document is not directly serializable, so you must rst use the
pub.document:documentToBytes service. Invoke the service and map the document to the
document input parameter. This will add the output documentBytes to the pipeline.

2. Invoke pub.cache:put and map documentBytes to the value input parameter for that
service. Set the key input parameter to a value that is meaningful to your application.

3. At another point in your application, you will need to retrieve the document you
cached. You can do so by invoking the pub.cache:get service and supplying the same
key input parameter as in step 2. The value output parameter that was added as
output to the pipeline will contain the byte array from step 1.

webMethods Integration Server Built-In Services Reference Version 9.6

227

Even Header
Document Folder

4. Invoke pub.document:bytesToDocument and map the value output parameter to the

documentBytes input parameter. This will add the output document to the pipeline,
which will match the original document in step 1.

pub.document:documentToDocumentList
WmPublic. Expands the contents of a document into a list of documents.
Each key/value pair in the source document is transformed to a single document
containing two keys (whose names you specify). These two keys will contain the key
name and value of the original pair.
Input Parameters
document

Document Document (IData object) to transform.

webMethods Integration Server Built-In Services Reference Version 9.6

228

Odd Header
Document Folder

name

String Name to assign to the key that will receive the key name from
the original key/value pair. (In the example above, this parameter
was set to pName.)

value

String Name to assign to the key that will receive the value from the
original key/value pair. (In the example above, this parameter was
set to pValue.)

Output Parameters
documentList

Document List List containing a document for each key/value pair

in the document parameter. Each document in the list will contain
two keys, whose names were specied by the name and value
parameters. The values of these two keys will be the name and
value (respectively) of the original pair.

Usage Notes
The following example shows how a document containing three keys would be
converted to a document list containing three documents. In this example, the names
pName and pValue are specied as names for the two new keys in the document list.
A document containing these three keys:
Key

Value

cx_timeout

1000

cx_max

2500

cx_min

10

Would be converted to a document list containing these three documents:

Key

Value

pName

cx_timeout

pValue

1000

Key

Value

pName

cx_max

webMethods Integration Server Built-In Services Reference Version 9.6

229

Even Header
Document Folder

Key

Value

pValue

2500

Key

Value

pName

cx_min

pValue

10

pub.document:documentToXMLValues
WmPublic. Converts a document (IData object) to a String by encoding it in the
webMethods XMLValues format.
Input Parameters
document

Document Document (IData object) to convert. This document can

contain any number of other elds, lists, and other documents.

Output Parameters
xmlvalues

String String representation of the document parameter, encoded

in the webMethods XMLValues format.

Usage Notes
To convert the encoded String back into an IData object, use the
pub.document:XMLValuesToDocument service.

pub.document:groupDocuments
WmPublic. Groups a set of documents based on specied criteria.
Input Parameters
documents

Document List Set of documents to be grouped based on the

specied criteria.

webMethods Integration Server Built-In Services Reference Version 9.6

230

Odd Header
Document Folder

groupCriteria

Document List The criteria on which the input documents are to be

grouped. Valid values for the groupCriteria parameter are:
key . Key in the pipeline. The value for key can be a path
expression. For example, "Family/Chidren[0]/BirthDate"
retrieves the birthday of the rst child from the input Family
document list.
compareStringsAs . Optional. Valid values for compareStringsAs
are string, numeric, and datetime. The default value is
string.
paern . Optional. paern will be considered only if the
compareStringsAs parameter is of type datetime. For
information about using paerns, see "Time Zones" on page 177.
Note: If key is not found in all the input documents, the
documents that do not match the groupCriteria are grouped
together as a single group.

Output Parameters
documentGroups

Document List List of documents where each element represents a

set of documents grouped based on the criteria specied.

Usage Notes
The following example illustrates how to specify the values for the groupCriteria
parameter:
key

compareStringsAs

name

string

age

numeric

birthdate

datetime

pattern

yyyy-MM-dd

The input documents will be grouped based on name, age, and birth date.

pub.document:insertDocument
WmPublic. Inserts a new document in a set of documents at a specied position.

webMethods Integration Server Built-In Services Reference Version 9.6

231

Even Header
Document Folder

Input Parameters
documents

Document List Set of documents in which a new document is to be

inserted.

insertDocument

Document The new document to be inserted to the set of

documents specied in the documents parameter.

index

String Optional. The position in the seat which the document is to

be inserted.
The index parameter is zero-based. if the value for the index
parameter is not specied, the document will be inserted at the
end of the document list specied in the documents parameter.

Output Parameters
documents

Document List Document list after inserting the new document.

pub.document:searchDocuments
WmPublic. Searches a set of documents for entries matching a set of Criteria.
Input Parameters
documents

Document List Set of documents from which the documents

meeting the search criteria are to be returned.

searchCriteria

Document Criteria on which the documents in the documents

parameter are to be searched.
Valid values for searchCriteria parameters are:
key . Name of the element in documentList whose value
provides the value for the search text. The value for key can
be a path expression. For example, "Family/Chidren[0]/
BirthDate" retrieves the birthday of the rst child from the
input Family document list.
value . Optional. Any search text. If no value is specied, the
service searches for null in the document list.
compareStringsAs . Optional. Allowed values are string,
numeric, and datetime. The default value is string.

webMethods Integration Server Built-In Services Reference Version 9.6

232

Odd Header
Document Folder

paern . Optional. paern will be considered only if the

compareStringsAs value is of type datetime. For information
about using paerns, see "Time Zones" on page 177.
String Optional. The value of the sorted parameter is true if the
document list is already sorted based on the search criteria and
same search key; otherwise false.

sorted

If the value for the sorted parameter is set to true, the required
documents are searched faster.
Output Parameters
resultdocuments

Document List List of documents which are matching the search

criteria.

documentListIndices

String List Positions of search documents in the document list.

documents

Document List List of documents that were input.

Usage Note
For example, if you want to search a set of documents for documents where BirthDate is
10th January 2008, the values for the searchCriteria parameter would be:
key

value

compareStringsAs

pattern

Birthdate

2008-01-10

datetime

yyyy-MM-dd

pub.document:sortDocuments
WmPublic. Sorts a set of input documents based on the specied sortCriteria.
Input Parameters
documents

Document List Set of documents that are to be sorted.

sortCriteria

Document List Criteria based on which the documents in the

documents parameter are to be sorted.
Valid values for sortCriteria parameters are:
key . Name of the element in documentList whose value provides
the value based on which the documents are to be sorted. The

webMethods Integration Server Built-In Services Reference Version 9.6

233

Even Header
Document Folder

value for key can be a path expression. For example, "Family/

Chidren[0]/BirthDate" retrieves the birthday of the rst child
from the input Family document list.

order . Optional. Allowed values are ascending and descending.

The default value is ascending.
compareStringsAs . Optional. Allowed values are string, numeric,
and datetime. Default value is string.
paern . Optional. The value for paern will be considered only if
the compareStringsAs value is of type datetime. For information
about using paerns, see "Time Zones" on page 177.
Note: If key is not found in all the input documents, the sorted list
of documents appears at the end or start of the list based on the
order specied. If the order is ascending, then all the documents
that do not match the sort criteria appears at the top of the list,
followed by the sorted list. If the order is descending, the sorted
list will appear at the top, followed by the documents that do not
match the sort criteria.
Output Parameters
documents

Document List The documents sorted based on the sort criteria

specied in the sortCriteria parameter.

Usage Notes
For example, if you want to sort a set of documents based on name, age, and then on
birth date, the values for sortCriteria parameter would be:
key

order

compareStringsAs

Name

ascending

string

Age

descending

numeric

Birthdate

ascending

datetime

pattern

yyyy-MM-dd

pub.document:XMLValuesToDocument
WmPublic. Decodes a String containing an XMLValues-encoded document and
produces a document (IData object).

webMethods Integration Server Built-In Services Reference Version 9.6

234

Odd Header
Document Folder

Input Parameters
xmlvalues

String An XMLValues encoding of a document.

Important: This String must contain a webMethods XMLValues
encoding of a document. No other encoding format is accepted.

Output Parameters
document

Document Document (IData object) result of the decoding of

xmlvalues .

Usage Notes
An XMLValues-encoded document is produced using pub.document:documentToXMLValues.

webMethods Integration Server Built-In Services Reference Version 9.6

235

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

236

Odd Header
Event Folder

7 Event Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

238

237

Even Header
Event Folder

You use the elements in the event folder to subscribe to events, write event handlers, and
work with EDA (Event Driven Architecture) events.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.event:addSubscriber

WmPublic. Creates a subscription for a

specied event.

pub.event:alarm

WmPublic. Specication for alarm event

handlers.

pub.event:alarmInfo

WmPublic. Document type for alarm event

information.

pub.event:audit

WmPublic. Specication for audit event

handlers.

pub.event:auditError

WmPublic. Specication for audit event errors.

pub.event:auditErrorInfo

WmPublic. Document type for audit error event

information.

pub.event:auditInfo

WmPublic. Document type for audit event

information.

pub.event:callstackItem

WmPublic. Document type for the name of

the service in the invocation path when an
exception occurred and the index that indicates
the step at which the exception occurred.

pub.event:deleteSubscriber

WmPublic. Removes an event handler from the

subscription list for a specied event.

pub.event.eda:event

WmPublic. Document type that denes the

structure of an event document.

pub.event.eda:eventToDocument

WmPublic. Converts an EDA event in the form

of an XML string to a document (IData object).

webMethods Integration Server Built-In Services Reference Version 9.6

238

Odd Header
Event Folder

Element

Package and Description

pub.event.eda:schema_event

WmPublic. Schema that denes the structure

and data types used for the event header in the
pub.event.eda:event document type.

pub.event.eda:send

WmPublic. Deprecated - Replaced by

pub.event.nerv:send.

pub.event:error

WmPublic. Specication for error event

handlers.

pub.event:errorInfo

WmPublic. Document type for error event

information.

pub.event:exception

WmPublic. Specication for exception event

handlers.

pub.event:exceptionInfo

WmPublic. Document type for exception

information.

pub.event:gdEnd

WmPublic. Specication for gdEnd event

handlers.

pub.event:gdEndInfo

WmPublic. Document type for gdEnd event

information.

pub.event:gdStart

WmPublic. Specication for gdStart event

handlers.

pub.event:gdStartInfo

WmPublic. Document type for gdStart event

information.

pub.event:getEventTypes

WmPublic. Returns the list of supported event

types on Integration Server.

pub.event:getSubscribers

WmPublic. Returns the list of subscribers for a

specied event type.

pub.event:jmsReceiveErrorEvent

WmPublic. Specication for a JMS retrieval

failure event handler.

webMethods Integration Server Built-In Services Reference Version 9.6

239

Even Header
Event Folder

Element

Package and Description

pub.event:jmsSendErrorEvent

WmPublic. Specication for the JMS delivery

failure event handler.

pub.event:journal

WmPublic. Specication for journal event

handlers.

pub.event:journalInfo

WmPublic. Document type for journal event

information

pub.event:modifySubscriber

WmPublic. Modies the information about a

subscription.

pub.event.nerv:eventToDocument

WmPublic. Converts an incoming JMS message

into an IS document (pub.event.eda:event).

pub.event.nerv:send

WmPublic. Sends an EDA event to the Network

for Event Routing and Variation (NERV).

pub.event:portStatus

WmPublic. Specication for a port status event.

pub.event:portStatusInfo

WmPublic. Document type for port event

information.

pub.event:reloadEventManagerSettings

WmPublic. Reloads the seings from the event

manager's conguration le (eventcfg.bin) on
the server.

pub.event:replication

WmPublic. Specication for replication event

handlers.

pub.event:replicationInfo

WmPublic. Document type for replication event

information.

pub.event:saveEventManagerSettings

WmPublic. Saves the current subscriber

information to the event manager's
conguration le (eventcfg.bin) on the server.

pub.event:security

WmPublic. Specication for security event

handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

240

Odd Header
Event Folder

Element

Package and Description

pub.event:securityInfo

WmPublic. Document type for security event

information.

pub.event:sessionEnd

WmPublic. Specication for sessionEnd event

handlers.

pub.event:sessionEndInfo

WmPublic. Document type for sessionEnd

event information.

pub.event:sessionExpire

WmPublic. Specication for sessionExpire event

handlers.

pub.event:sessionExpireInfo

WmPublic. Document type for sessionExpire

event information.

pub.event:sessionStart

WmPublic. Specication for sessionStart event

handlers.

pub.event:sessionStartInfo

WmPublic. Document type for sessionStart

event information.

pub.event:stat

WmPublic. Specication for stat event handlers.

pub.event:statInfo

WmPublic. Document type for stat event

information.

pub.event:txEnd

WmPublic. Specication for txEnd event

handlers.

pub.event:txEndInfo

WmPublic. Document type for txEnd event

information.

pub.event:txStart

WmPublic. Specication for txStart event

handlers.

pub.event:txStartInfo

WmPublic. Document type for txStart event

information.

webMethods Integration Server Built-In Services Reference Version 9.6

241

Even Header
Event Folder

pub.event:addSubscriber
WmPublic. Creates a subscription for a specied event.
Important: Subscriptions that you add using this service take eect immediately;
however, they are not made permanent unless you also persist them to
disk with the pub.event:saveEventManagerSettings service. If you do not run
pub.event:saveEventManagerSettings after adding subscribers, your changes will be lost when
the server is restarted.
Input Parameters
EventType

String Type of event to which the event handler is subscribing.

Must be one of the following:
Alarm Event
Audit Event
Audit Error Event
Error Event
Exception Event
GD End Event
AGD Start Event
JMS Delivery Failure Event
JMS Retrieval Failure Event
Journal Event
Port Status Event
Replication Event
Security Event
Session End Event
Session Expire Event
Session Start Event
Stat Event
Tx End Event
Tx Start Event

Tip: To view the current list of event types, you can execute the
pub.event:getEventTypes service.
Filter

String Selects (lters) the set of events within EventType to which

the event handler is subscribing. addSubscriber uses Filter as a
paern string to lter a particular aribute of an event.

webMethods Integration Server Built-In Services Reference Version 9.6

242

Odd Header
Event Folder

The paern string can be composed of literal characters, which

match a character exactly, and/or the "*" character, which matches
any sequence of characters. For example:
This pattern
string...

Would match...

Any string

M*

Any string that starts with an uppercase "M."

M*X

Any string that starts with an uppercase "M"

and ends with an uppercase "X."

The following table shows the aribute that is ltered for each
event type. Note that some event types cannot be ltered.
EventType

Filtered attribute

Alarm Event

Message generated by the alarm event.

Audit Event

Fully qualied name of the service that

generates the audit event.

Audit Error
Event

Concatenated values of the destination and

errorCode parameters of the audit error event.

Error Event

Error message text for the error that

generates the error event.

Exception
Event

Fully qualied name of the service that

generates the exception event.

GD End Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

GD Start Event

Fully qualied name of the service that

generates the GD Start Event.

JMS Delivery
Failure Event

Name of the JMS connection alias used to

send the message to the JMS provider.

webMethods Integration Server Built-In Services Reference Version 9.6

243

Even Header
Event Folder

JMS Retrieval
Failure Event

Fully qualied name of the JMS trigger that

invoked the trigger service for which the
error occurred.

Journal Event

The major code and minor code of the

message that causes the journal event.

Port Status
Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Replication
Event

Name of the package being replicated.

Security Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Session End
Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Session Expire
Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Session Start
Event

User ID of the user starting the session or the

groups to which the user belongs. (The lter
is applied to a space-delimited list of groups,
composed of group names suxed with the
user's user ID.)
The following examples show how you
might lter session start events for various
groups and/or user IDs:
To select session starts for any user in the
Administrators group, the lter would be:
*Administrators*

To select session starts for the user ID

"LRMalley" in the Administrators group, the
lter would be:
*Administrators*LRMalley

To select session starts for the user ID

"LRMalley" in any group, the lter would be:
*LRMalley

Stat Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

webMethods Integration Server Built-In Services Reference Version 9.6

244

Odd Header
Event Folder

Tx End Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Tx Start Event

None. This event type cannot be ltered.

Filter is ignored for this event type.

Service

String Fully qualied name of the event-handler service (the service

that will execute when the event specied by EventType and Filter
occurs).

Comment

String Descriptive comment for this subscription. This comment is

displayed when subscriptions are viewed with Designer.

Enabled

String Flag specifying the status of the subscription. Must be one of

the following values. Set to:
true to make the subscription active.
false to make the subscription inactive. This is the default.

Note: Although the default value is false, you will generally want
to set Enabled to true to activate the subscription immediately
when it is added.
Output Parameters
Result

String Flag indicating whether the subscriber was successfully

added. A value of:
true indicates that the subscriber was added successfully.
false indicates that the subscriber was not added.

See Also
pub.event:deleteSubscriber
pub.event:modifySubscriber
pub.event:getSubscribers
pub.event:saveEventManagerSettings

pub.event:alarm
WmPublic. Specication for alarm event handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

245

Even Header
Event Folder

Input Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/
dd HH:mm:ss.SS .

service

String Fully qualied name of the service that generated the event. A
service can generate an alarm event when a client invokes a service
that accesses information or a service on a remote server. If the client
is not a member of an allowed group for the port on the remote
server, the service will generate an alarm event.

sessionID

String Identication number for the session during which the alarm
event was generated. Some alarm events are not generated during
sessions. In these cases, the sessionID variable will not contain a
value.

msg

String Text describing the alarm.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
When you subscribe an event handler to an alarm event, you can create a lter for the
msg eld to specify the services whose alarm events you want to subscribe to. That is,
you can specify which services' alarm events invoke the event handler.

pub.event:alarmInfo
WmPublic. Document type for alarm event information.
Parameters
time

String Date and time that the event occurred, in the format yyyy/
MM/dd HH:mm:ss.SS .

service

String Fully qualied name of the service that generated the event.

sessionID

String Session ID of the service ring the alarm.

msg

String Text describing the alarm.

webMethods Integration Server Built-In Services Reference Version 9.6

246

Odd Header
Event Folder

pub.event:audit
WmPublic. Specication for audit event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy-MMdd HH:mm:ss z (for example, "2004-10-28 14:46:39 EDT").
Note: You can set the format for the time parameter in the
wa.server.dateStampFmt property.

TID

String Server thread that generated the audit event.

service

String Fully qualied name of the service that generated the event.

sessionID

String Session ID of the service that generated the event.

result

String Description of the audit point. A value of:

Started indicates that this event marks the beginning of a service.
Ended indicates that this event marks the end of a service that

executed successfully.

Failed indicates that this event marks the end of a service that

executed unsuccessfully (that is, threw an exception) and is not

congured to retry. A failed event also marks the end of a service
that executed unsuccessfully after exhausting all of its retries.
Retried indicates that this event is created each time a service is

retried.
pipeline

Document Optional. The pipeline that was passed to the service. This
parameter is required only if the service is congured to include the
pipeline when auditing.

userName

String User ID that invoked the service that generated the event.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

247

Even Header
Event Folder

Usage Notes
Events are created for a service only if auditing for that type of event is enabled for the
service. For example, start events will not be created unless auditing for service start is
enabled for that service.
Remember to register your handler with the Event Manager. Not all audit handlers that
you code will log information.
When writing your own audit handler, be careful to not modify the pipeline variable
within your handler.
Use the wa.server.event.audit.async server parameter to indicate whether event
handlers for audit events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to audit events asynchronously. When this parameter is set to false, Integration Server
invokes the event handlers that subscribe to audit events synchronously. The default is
true (asynchronous).

pub.event:auditError
WmPublic. Specication for audit error event handlers.
Input Parameters
time

String Date and time at which the audit error occurred. This
parameter is in the format yyyy-MM-dd HH:mm:ss.SSS (for
example, "2004-10-28 14:46:39.505").

destination

String Species the audit log destination to which the audit

logging system aempted to write when the error occurred.

message

Value

Audit logger where the error occurred

ServiceDBDest

Service audit logger

ErrorDBDest

Error audit logger

SessionDBDest

Session audit logger

ProcessAuditDBDest

Process audit logger

CoreAuditDBDest

All other audit loggers

String Error message of the exception.

webMethods Integration Server Built-In Services Reference Version 9.6

248

Odd Header
Event Folder

stackTrace

String Stack trace for the exception.

errorCode

String Optional. The SQL error code returned with the exception.

Output Parameters
None.
Usage Notes
Remember to register your event handler using pub.event:addSubscriber. Set the EventType
input variable to Audit Error Event.
An audit error event is red in the following situations:
When a SQLException is encountered while trying to insert an audit record into the
audit logging database.
When Integration Server initializes and cannot connect to the audit logging database.
When the Service logger is congured to retry failed auditing aempts, the audit
error event is red for the initial failure and each subsequent failure.
When you subscribe to an audit error event, you can supply a lter to limit the events
that your event handler receives. The lter applies to the concatenated values of the
destination and errorCode elds. You can use the asterisk (*) as a wildcard character in
the lter. The following table shows how you can use lters to limit the events that your
event handler will receive:
This filter...

Limits the events that the event handler receives to...

YourSearchTerm

Events that contain onlyYourSearchTerm .

*YourSearchTerm

Events that contain YourSearchTerm at the end of the audit error

event value.

YourSearchTerm*

Events that contain YourSearchTerm at the beginning of the

audit error event value.

*YourSearchTerm*

Events that contain YourSearchTerm anywhere within the audit

error event value.

Use the wa.server.event.audit.async server parameter to indicate whether event

handlers for audit error events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to audit error events asynchronously. When this parameter is set to false, Integration
Server invokes the event handlers that subscribe to audit error events synchronously.
The default is true (asynchronous).

webMethods Integration Server Built-In Services Reference Version 9.6

249

Even Header
Event Folder

pub.event:auditErrorInfo
WmPublic. Document type for audit error event information.
Input Parameters
time

String Date and time at which the audit error occurred. This
parameter is in the format yyyy-MM-dd HH:mm:ss.SSS (for
example, "2004-10-28 14:46:39.505").

destination

String Species the audit log destination to which the audit

logging system aempted to write when the error occurred.
Value

Audit logger where the error occurred

ServiceDBDest

Service audit logger

ErrorDBDest

Error audit logger

SessionDBDest

Session audit logger

ProcessAuditDBDest

Process audit logger

CoreAuditDBDest

All other audit loggers

message

String Error message of the exception.

stackTrace

String Stack trace for the exception.

errorCode

String Optional. The SQL error code returned with the exception.

Usage Notes
Use the wa.server.event.audit.async server parameter to indicate whether event
handlers for audit events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe to
audit events asynchronously. When this parameter is set to false, Integration Server
invokes the event handlers that subscribe to audit events synchronously. The default is
true (asynchronous).

webMethods Integration Server Built-In Services Reference Version 9.6

250

Odd Header
Event Folder

pub.event:auditInfo
WmPublic. Document type for audit event information.
Parameters
time

String Date and time that the event occurred, in the format yyyy-MMdd HH:mm:ss z (for example, "2004-10-28 14:46:39 EDT").
Note: You can set the format for the time parameter in the
wa.server.dateStampFmt property.

TID

String Server thread that generated the audit event in

hashed format. The TID is generated by calling the Java
Thread.currentThread().hashCode() method.

service

String Fully qualied name of the service that generated the event.

sessionID

String Session ID of the service that generated the event.

result

String Description of the audit point.

Started indicates that this event marks the beginning of a service.
Ended indicates that this event marks the end of a service that

executed successfully.

Failed indicates that this event marks the end of a service that

executed unsuccessfully (that is, threw an exception) and is not

congured to retry. A failed event also marks the end of a service
that executed unsuccessfully after exhausting all of its retries.
Retried indicates that this event is created each time a service is

retried.
pipeline

Document Optional. The pipeline that was passed to the service. This
parameter is required only if the service is congured to include the
pipeline when auditing.

userName

String User ID that invoked the service that generated the event.

Usage Notes
Use the wa.server.event.audit.async server parameter to indicate whether event
handlers for audit events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe to
webMethods Integration Server Built-In Services Reference Version 9.6

251

Even Header
Event Folder

audit events asynchronously. When this parameter is set to false, Integration Server
invokes the event handlers that subscribe to audit events synchronously. The default is
true (asynchronous).

pub.event:callstackItem
WmPublic. Document type for the name of the service in the invocation path when an
exception occurred and the index that indicates the step at which the exception occurred.
Parameters
service

String Fully qualied name of the last service (that is, most recently
called) on the call stack.

owStep

String Path representing the last executed ow step in the service

where the exception occurred. The path takes the form /n/n/n...,
where n represents a sequential index of ow steps and / indicates
a level of nesting. The following illustrates an example of ow
steps and the owStep value that would be assigned to them if the
exception occurred at that step:
Step

flowStep Value

MAP
SEQUENCE
BRANCH
INVOKE
MAP
SEQUENCE
EXIT

/0
/1
/1/0
/1/0/0
/2
/3
/3/0

If the stack contains a Java service, the owStep value for that
service will be empty.

pub.event:deleteSubscriber
WmPublic. Removes an event handler from the subscription list for a specied event.
Important: Deletions made using this service take eect immediately;
however, they are not made permanent unless you persist them to
disk with the pub.event:saveEventManagerSettings service. If you do not run
pub.event:saveEventManagerSettings after deleting subscribers, your changes will be lost
when the server is restarted.

webMethods Integration Server Built-In Services Reference Version 9.6

252

Odd Header
Event Folder

Input Parameters
EventType

String Type of event from which the event handler is unsubscribing.

Must be one of the following values:
Alarm Event
Audit Event
Exception Event
GD End Event
GD Start Event
JMS Delivery Failure Event
JMS Retrieval Failure Event
Port Status Event
Replication Event
Security Event
Session End Event
Session Expire Event
Session Start Event
Stat Event
Tx End Event
Tx Start Event

Tip: To view the current list of event types, you can execute the
pub.event:getEventTypes service.
String ID of the subscriber that you want to delete. To get a list of
subscriber IDs, execute the pub.event:getSubscribers service.

gID

Output Parameters
Result

String Flag indicating whether the subscriber was successfully

deleted. A value of:
true indicates that the subscriber was deleted successfully.
false indicates that the subscriber was not deleted (typically an

invalid subscriber ID was provided in gID ).

See Also
pub.event:addSubscriber
pub.event:modifySubscriber
pub.event:getSubscribers
pub.event:saveEventManagerSettings

webMethods Integration Server Built-In Services Reference Version 9.6

253

Even Header
Event Folder

pub.event.eda:event
WmPublic. Document type that denes the structure of an EDA event.
Parameters
evt:Header

Document The event header.

Key

Description

evt:Start

String Start date and time of the event, in the

format yyyy-MM-dd'T'HH:mm:ss.SSSZ .

evt:End

String Optional. End date and time of the event,

in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ .
The absence of an End value in an event is often
interpreted as indicating that the event started
and ended at the same time. While this is valid
in some consumers, other consumers consider it
impossible for events to start and end at precisely
the same time. When an event does not specify
an End value, the consumer may set a default
value, such as start time plus one millisecond.

evt:Kind

String Optional. Indicates whether the event

is a new event (Event) or a heartbeat event
(Heartbeat). A heartbeat event indicates the
temporal progress of the stream.

evt:Type

String The unique identier of the event type.

Event Types use qualied names (QNames)
as the mechanism for concisely identifying the
particular type. The value of evt:type combines
the URI and local name as a string. For example,

{http://namespaces.softwareag.com/EDA/
WebM/Process/1.0}ProcessInstanceChange is

the event type identier that reports changes to a

process instance.

evt:Version

String Optional. The version of the event type

with which the event is compatible. An event
should contain a version only if the event type
supports versioning. An event should not specify

webMethods Integration Server Built-In Services Reference Version 9.6

254

Odd Header
Event Folder

a version if the event type does not support

versioning.

evt:Body

evt:CorrelationID

String Optional. Unique identier used to

associate an event with other events.

evt:EventID

String Optional. The unique identier of the

event. This element can be supplied by the
user who emied the event or can be system
generated.

evt:Priority

String Optional. The priority of the event to the

producer. The value can be Normal or High.

evt:ProducerID

String Optional. The identier of the event

producer. For example, this can be an application
identier or a globally unique identier for each
producer.

evt:UserID

String Optional. The identier of the user who

emied the event.

evt:CustomHeaders

Document Optional. Custom header elements.

Document Optional. The event body.

Usage Notes
The prex evt is associated with the namespace hp://namespaces.softwareag.com/
EDA/Event. All events belong to this asset namespace.
The pub.event.eda:schema_event schema denes the structure and data types for an EDA
event document.

pub.event.eda:eventToDocument
WmPublic. Converts an EDA event in the form of an XML string to a document instance
in the form of pub.event.eda:event.
Input Parameters
xmldata

String XML string containing the event to convert to a

document (IData object). The XML string must conform to the
Event element structure declared in the Envelope.xsd schema.

webMethods Integration Server Built-In Services Reference Version 9.6

255

Even Header
Event Folder

documentTypeName

String Optional. Fully qualied name of the IS document type

that species the structure to impose on the body of the event.
By specifying a document type, you can identify:
The order and dimensionality of elements.
The prex associated with each namespace in the instance
document.
The document type specied in documentTypeName does not
need to specify every element that will appear in the resulting
document. At a minimum, the document type needs to specify
the elements whose structure you want to explicitly set and the
elements that you want to use in pipeline mapping.
If you do not specify documentTypeName , the structure of the
event body is determined solely by the event document.

Output Parameters
evt:Event

Document A document reference to the pub.event.eda:event document

type which species the structure of an event as a Document
(IData object).

Usage Notes
This service transforms each element and aribute in the EDA event to an element in an
IData object.
This service always converts XML nodes to String or Document object elds. It does not
generate constrained objects (for example, Floats or Integers), even if the elds in the
specied document are dened as constrained objects.
The pub.event.eda:event document type determines the overall structure of the evt:Event
IData object that this service returns.
The document type specied for documentTypeName determines the structure of the
event body contained in the evt:Body eld. If you do not specify documentTypeName , the
structure of the event body is determined by the event.
The document type in documentTypeName identies the namespace prexes
to use for the conversion. Integration Server determines the namespace prex
information through the association of the prex in the eld name with the URI
in the XML namespace property of the eld. For example, suppose that a eld in
documentTypeName is named SAG:account and the XML namespace property of that
eld is hp://www.softwareag.com. In the resulting IData object for the event body,
Integration Server will use the prex SAG with any element that belongs to the hp://
www.softwareag.com namespace.

webMethods Integration Server Built-In Services Reference Version 9.6

256

Odd Header
Event Folder

If documentTypeName does not specify namespace prexes or documentTypeName is not

specied, the prexes used in conversion depend on the event document.
If the event contains namespace qualied elements and uses prexes, the resulting
IData object for the event body uses the prexes from the instance document.
If the event contains elements qualied with a default namespace and the elements
do not use prexes, the resulting IData object for the event body does not use
prexes. Only the local name appears in the resulting event body.
In a document type that represents a namespace qualied XML document, it is
considered good practice for the document type and its contents to account for all of
the namespaces in the XML document. That is, the document type should include
namespace prexed elds associated with the namespaces for all of the possible
namespace qualied elements in the XML document.
When documentTypeName is provided, the server parameter
wa.server.xml.xmlNodeToDocument.keepDuplicates determines whether or not
Integration Server keeps additional occurrences of an element in an XML document.
When set to true, the document produced by the pub.event.eda:eventToDocument service
contains multiple occurrences of the element. When set to false, the document keeps
only the last occurrence of the element. The default is true.
The pub.event.eda:eventToDocumentservice is used to convert events formaed with
Integration Server version 8.2 into IData. To convert events formaed with Integration
Server version 9.0 to IData, use the pub.event.nerv:eventToDocument service.

pub.event.eda:schema_event
WmPublic. Schema that denes the structure and data types used for the event header in
the pub.event.eda:event document type.

pub.event.eda:send
WmPublic. Deprecated - Replaced by pub.event.nerv:send.
Sends an EDA event to a JMS provider.
Input Parameters
eventTypeName

Document Document that species the qualied name for the event
type for the EDA event.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

257

Even Header
Event Folder

documentType
Name

namespaceName

String The namespace portion of the event type

qualied name. This is typically a URI.

localName

String The local portion of the event type

qualied name. This is typically an element
name or the name of a eld in a document type
that corresponds to an element.

String Fully qualied name of the IS document type that species

the structure to impose on the body of the event. By specifying a
document type, you can identify:
The order and dimensionality of elements.
The prex associated with each namespace in the instance
document.
When eld names in a document type include a prex
and specify a value for the XML namespace property, the
pub.event.eda:send service will convert a name/value pair in the
event/body IData with the same prex and name to an XML
element with that prex and with a local name equivalent to the
XML namespace property value.

connectionAlias
Name

String Name of the JMS connection alias that you want to use to
send the message.
The JMS connection alias indicates how Integration Server
connects to the JMS provider. A JMS connection alias can
specify that Integration Server use a JNDI provider to look up
administered objects (connection factories and destinations)
and then use the connection factory to create a connection.
Alternatively, a JMS connection alias can specify that Integration
Server uses the native webMethods API to create the connection
directly on the webMethods Broker.

destinationName

String Optional. Name or lookup name of the Topic to which you

want to send the message. Specify the lookup name of the Topic
when the JMS connection alias uses JNDI to retrieve administered
objects. Specify the provider-specic name of the Topic when the
JMS connection alias uses the native webMethods API to connect
directly to the webMethods Broker.
Specify a destinationName if you want to override the destination
specied for the event type in the event type store only.
Note: The pub.event.eda:send service sends messages to Topics only.

webMethods Integration Server Built-In Services Reference Version 9.6

258

Odd Header
Event Folder

event

Document Optional. A document containing the event that you

want to publish, including the event header and payload.
Key

Description

header

Document Optional. A document containing the

information that you want to set in the event
header.

body

useCSQ

Key

Description

start

java.util.date Optional. Start

date and time of the event.
If you do not specify a start
value, the pub.event.eda:send
service uses the current date
and time.

end

java.util.date Optional. End

date and time of the event.
The pub.event.eda:sendservice
ignores an end value if start is
not specied.

version

String Optional. Version of

the event type with which the
event is compatible. An event
should contain a version only
if the event type supports
versioning.

correlationID

String Optional. Unique

identier used to associate
this event with other events.

Document Optional. A document (IData)

containing the payload for the event. If this is
a heartbeat event, do not specify a value for
body .

java.lang.Boolean Optional. Flag indicating whether Integration

Server places sent messages in the client side queue if the JMS
provider is not available at the time the messages are sent. Set to:
True to write messages to the client side queue if the JMS

provider is not available at the time this service executes. When

webMethods Integration Server Built-In Services Reference Version 9.6

259

Even Header
Event Folder

the JMS provider becomes available, Integration Server sends

messages from the client side queue to the JMS provider. This is
the default.
False to throw an ISRuntimeException if the JMS provider is

not available at the time this service executes.

Note: If the specied connectionAliasName is a transacted JMS

connection alias or uses a cluster connection factory to which
the multisend guaranteed policy is applied, set useCSQ to
False.
Output Parameters
JMSMessage

Document. A Document containing the event sent to the JMS

provider as a JMS message.
Key

Description

header

Document Conditional. A Document containing the

header elds for the sent message. The JMS provider
populates these elds after it has successfully
received the message from Integration Server.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link messages
together.

JMSDeliveryMode

java.lang.Integer Delivery mode

used to send the message.
PERSISTENT or 2 indicates that

the JMS provider provides onceand-only-once delivery for the

message. The message will not
be lost if a JMS provider failure
occurs.
NON_PERSISTENT or 1 indicates

that the JMS provider provides

at-most-once delivery for the
message. The message has no
guarantee of being saved if a JMS
provider failure occurs.

webMethods Integration Server Built-In Services Reference Version 9.6

260

Odd Header
Event Folder

JMSDestination

Object Conditional. Topic to

which the message was sent.

JMSExpiration

java.lang.LongConditional. Time
at which this message expires.
If the message producer did
not specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does not
expire.

JMSMessageID

String Conditional. Unique

identier assigned to this
message by the JMS provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message priority. The
JMS standard denes priority
levels from 0 to 9, with 0 as the
lowest priority and 9 as the
highest.

JMSRedelivered

java.lang.Boolean Conditional.
Flag indicating the JMS provider
delivered this message to the
JMS client previously.
True indicates the message may

have been delivered in the past.

False indicates the JMS provider

has not delivered this message

previously.
JMSReplyTo

Object Conditional. Species the

destination to which a response
to this message should be sent.
If the message producer did not
specify a replyTo destination,
this parameter is null.

JMSTimestamp

java.lang.Long Time at which the

message was given to the JMS
provider.

webMethods Integration Server Built-In Services Reference Version 9.6

261

Even Header
Event Folder

JMSType

properties

String Conditional. Message type

identier specied by the client
when sending the message.

Document Conditional. A Document containing

optional elds added to the message header. These
properties
Integration Server obtains the properties specic to
the event type and adds them as name/value pairs to
the JMS message header.

body

Document Conditional. A Document containing the

JMS message body. Integration Server supports the
following formats for the JMS message body:
Key

Description

string

String Conditional. Message body

in the form of a String.

Usage Notes
The pub.event.eda:send service sends an event in the form of a JMS message to a JMS
provider. You can send a regular EDA event or a heartbeat event for the specied event
type in eventTypeName . The pub.event.eda:send service infers whether the event is a regular
event or a heartbeat event based on the presence of the body parameter. To send a
heartbeat event, do not specify a value for the body parameter.
Integration Server returns the output parameter JMSMessage because some of the header
elds in a JMS message are populated by the JMS provider after the message is sent. For
example, the header eld JMSMessageID is not in the JMS message sent by Integration
Server, but JMSMessageID is in the header after the JMS provider receives the message.
If the JMS provider is not available at the time pub.event.eda:sendexecutes and useCSQ is
set to true, the header elds in the output JMSMessage will not be populated. Instead
these elds will be blank or be set to 0 (zero).
Each JMS connection alias has its own client side queue. Integration Server places
messages in the client side queue if the JMS provider is not available at the time the
pub.event.eda:send service executes. When the JMS provider becomes available, Integration
Server sends messages from the client side queue to the JMS provider.
If client side queuing is not used (useCSQ is set to false), Integration Server throws an
ISRuntimeException if the JMS provider is not available when this service executes.
Make sure to code your service to handle this situation.
When sending a message as part of a transaction client side queuing cannot be used.
That is, the useCSQ eld should be set to false. If useCSQ is set to true, Integration
Server throws a JMSSubsystemException when the pub.event.eda:send service executes.
webMethods Integration Server Built-In Services Reference Version 9.6

262

Odd Header
Event Folder

A JMS message is sent as part of a transaction if the JMS connection alias specied in
connectionAliasName :
Uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
Connects to the webMethods Broker using a cluster connection factory to which the
multisend guaranteed policy is applied. Integration Server uses an XA transaction to
perform a two-phase commit when sending JMS messages.

pub.event:error
WmPublic. Specication for error event handlers.
Input Parameters
stackTrace

String Stack trace for the error.

errorMessage

String The error message, if any, generated by the error that causes
the error event.

serviceName

String Fully qualied name of the service in which the error

occurred.

Output Parameters
None.
Usage Notes
Remember to register your even handler using Event Manager orpub.event:addSubscriber.
The wa.server.event.exception.async server parameter indicates whether event
handlers for error events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to error events asynchronously. When this parameter is set to false, Integration Server
invokes the services that subscribe to the error events synchronously. The default is true
(asynchronous).
An error event handler can have a lter for the contents of errorMessage . The following
lter species that any error event with an errorMessage whose value contains the word
"missing" will invoke the event handler: *missing*

pub.event:errorInfo
WmPublic. Document type for error event information.

webMethods Integration Server Built-In Services Reference Version 9.6

263

Even Header
Event Folder

Parameters
stackTrace

String Stack trace for the error.

errorMessage

String The error message, if any, generated by the error that causes
the error event.

serviceName

String Fully qualied name of the service in which the error

occurred.

Usage Note
The wa.server.event.exception.async server parameter indicates whether event
handlers for error events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to error events asynchronously. When this parameter is set to false, Integration Server
invokes the services that subscribe to the error events synchronously. The default is true
(asynchronous).
An error event handler can have a lter for the contents of errorMessage . The following
lter species that any error event with an errorMessage whose value contains the word
"missing" will invoke the event handler: *missing*

pub.event:exception
WmPublic. Specication for exception event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS .
Note: You can set the format by specifying the
wa.server.dateStampFmt property.

error

String Optional. Error message of the exception.

localizedError

String Optional. Error message in the language that

corresponds to the locale of your webMethods installation.

errorType

String Exception type that was thrown.

errorDump

String More detailed information about the exception.

webMethods Integration Server Built-In Services Reference Version 9.6

264

Odd Header
Event Folder

service

String Optional. Fully qualied name of the service that

generated the event.

user

String User that requested the service that generated the event.

callStack

Document List Optional. The call stack information describing

where the exception occurred, including the fully qualied
name of a service on the stack and an index that identies
the last executed ow step in that service. Each document
represents a service on the call stack. The rst document in
the list represents the service that threw the exception and the
last document in the list represents the top-level service. The
structure of this document is dened by pub.event:callstackItem.

pipeline

Document Optional. State of the pipeline at the time the

exception occurred.

threadID

String Thread ID identifying the thread that invoked the

service.

ssnid

String Session ID during which the exception occurred.

errorMsgID

String Optional. The identication number for the error

message.

errorDetails

Document Optional. Additional exception information

provided by the author of the Java service. For more
information about constructing exceptions to return additional
information, see the webMethods Integration Server Java API
Reference for the com.wm.util.LocalizedException class.

nestedErrorInfo

Document Optional. Nested errors and exceptions, if any. The

structure of this document is dened by pub.event:exceptionInfo.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Not all exception handlers that you code will log information.
Use the wa.server.event.exception.async server parameter to indicate whether event
handlers for exception events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe

webMethods Integration Server Built-In Services Reference Version 9.6

265

Even Header
Event Folder

to exception events asynchronously. When this parameter is set to false, Integration

Server invokes the services that subscribe to the exception events synchronously. The
default is true (asynchronous).
When you subscribe an event handler to an exception event, you can create a lter for
the service eld to specify the services whose exception events you want to subscribe to.
That is, you can specify which services' exception events invoke the event handler.

pub.event:exceptionInfo
WmPublic. Document type for exception information.
Parameters
time

String Date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS .

error

String Optional. Error message of the exception.

localizedError

String Optional. Error message in the language that

corresponds to the locale of your webMethods installation.

errorType

String Exception type that was thrown.

errorDump

String More detailed information about the exception.

service

String Optional. Fully qualied name of the service that

generated the event.

user

String User that requested the service that generated the event.

callStack

Document List Optional. The call stack information describing

where the exception occurred, including the fully qualied
name of a service on the stack and an index that identies
the last executed ow step in that service. Each document
represents a service on the call stack. The rst document in
the list represents the service that threw the exception and the
last document in the list represents the top-level service. The
structure of this document is dened by pub.event:callstackItem.

pipeline

Document Optional. State of the pipeline at the time the

exception occurred.

webMethods Integration Server Built-In Services Reference Version 9.6

266

Odd Header
Event Folder

threadID

String Thread ID identifying the thread that invoked the

service.

ssnid

String Session ID during which the exception occurred.

errorMsgID

String Optional. The identication number for the error

message.

errorDetails

Document Optional. Additional exception information

provided by the author of the Java service. For more
information about constructing exceptions to return additional
information, see the webMethods Integration Server Java API
Reference for the com.wm.util.LocalizedException class.

nestedErrorInfo

Document Optional. Nested errors and exceptions, if any. The

structure of this document is dened by pub.event:exceptionInfo.

Usage Notes
Use the wa.server.event.exception.async server parameter to indicate whether event
handlers for exception events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to exception events asynchronously. When this parameter is set to false, Integration
Server invokes the services that subscribe to the exception events synchronously. The
default is true (asynchronous).

pub.event:gdEnd
WmPublic. Specication for gdEnd event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

267

Even Header
Event Folder

Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.gd.async server parameter to indicate whether event handlers
for all guaranteed delivery events (gdStart and gdEnd) are invoked synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to the gdStart and/or gdEnd events asynchronously.
When this parameter is set to false, Integration Server invokes the event handlers
that subscribe to the gdStart and/or gdEnd events synchronously. The default is true
(asynchronous).

pub.event:gdEndInfo
WmPublic. Document type for gdEnd event information.
Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS.

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Usage Notes
Use the wa.server.event.gd.async server parameter to indicate whether event handlers
for all guaranteed delivery events (gdStart and gdEnd) are invoked synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to the gdStart and/or gdEnd events asynchronously.
When this parameter is set to false, Integration Server invokes the event handlers
that subscribe to the gdStart and/or gdEnd events synchronously. The default is true
(asynchronous).

pub.event:gdStart
WmPublic. Specication for gdStart event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS.

webMethods Integration Server Built-In Services Reference Version 9.6

268

Odd Header
Event Folder

TID

String Transaction ID of the service that generated the event.

svcname

String Fully qualied name of the service that generated the event.

result

String Status of the transaction.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.gd.async server parameter to indicate whether event handlers
for all guaranteed delivery events (gdStart and gdEnd) are invoked synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to the gdStart and/or gdEnd events asynchronously.
When this parameter is set to false, Integration Server invokes the event handlers
that subscribe to the gdStart and/or gdEnd events synchronously. The default is true
(asynchronous).
When you subscribe an event handler to a gdStart event, you can create a lter for the
svcname eld to specify the services in a guaranteed delivery transaction that you want
to subscribe to. That is, you can specify the services that when invoked using guaranteed
delivery will invoke the event handler.

pub.event:gdStartInfo
WmPublic. Document type for gdStart event information.
Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

svcname

String Fully qualied name of the service that generated the event.

result

String Status of the transaction.

Usage Notes
Use the wa.server.event.gd.async server parameter to indicate whether event handlers
for all guaranteed delivery events (gdStart and gdEnd) are invoked synchronously or
webMethods Integration Server Built-In Services Reference Version 9.6

269

Even Header
Event Folder

asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to the gdStart and/or gdEnd events asynchronously.
When this parameter is set to false, Integration Server invokes the event handlers
that subscribe to the gdStart and/or gdEnd events synchronously. The default is true
(asynchronous).

pub.event:getEventTypes
WmPublic. Returns the list of supported event types on Integration Server.
Input Parameters
None.
Output Parameters
EventTypes

Document The types of events that the server supports:

Alarm Event
Audit Event
Audit Error Event
Exception Event
GD End Event
GD Start Event
JMS Delivery Failure Event
JMS Retrieval Failure Event
Port Status Event
Replication Event
Security Event
Session End Event
Session Expire Event
Session Start Event
Stat Event
Tx End Event
Tx Start Event

Usage Note
The pub.event:getEventTypes service returns a list of supported local event types on
Integration Server. The service does not return a list of EDA event types in the event
store.

pub.event:getSubscribers
WmPublic. Returns the list of subscribers for a specied event type.

webMethods Integration Server Built-In Services Reference Version 9.6

270

Odd Header
Event Folder

Input Parameters
EventType

String Type of event for which you want the list of subscribers. Must
be one of the following values:
Alarm Event
Audit Event
Audit Error Event
Exception Event
GD End Event
GD Start Event
JMS Delivery Failure Event
JMS Retrieval Failure Event
Port Status Event
Replication Event
Security Event
Session End Event
Session Expire Event
Session Start Event
Stat Event
Tx End Event
Tx Start Event

Tip: To view the current list of event types, you can execute the
pub.event:getEventTypes service.
Output Parameters
Subscribers

Document The list of subscribers. For each subscriber, Subscribers

will contain a key that is the subscriber ID. The value of that key is a
document containing the following information about the subscriber:
Key

Description

Service

String Fully qualied name of the event-handler

service (that is, the service that subscribes to the
event in EventType ).

Filter

String Filter associated with the subscription. This

is a paern string that selects (lters) an event
based on a particular aribute. Filter is composed
of literal characters, which match a character
exactly, and/or the "*" character, which matches
any sequence of characters. For example:

webMethods Integration Server Built-In Services Reference Version 9.6

271

Even Header
Event Folder

* would math any string.

M* would math any string that starts with an

uppercase "M."

M*X would math any string that starts with an

uppercase "M" and ends with an uppercase "X."

For a list of aributes to which the lter is applied,
see pub.event:addSubscriber.
Comment

String Descriptive comment associated with the

description. If a comment has not been assigned to
the subscription, Comment will be empty.

gID

String Subscriber ID.

Enabled

String Flag indicating the status of the subscription.

Will be one of the following values. A value of:
true indicates that the subscription is active.
false indicates that the subscription is inactive.

See Also
pub.event:addSubscriber
pub.event:modifySubscriber
pub.event:deleteSubscriber

pub.event:jmsReceiveErrorEvent
WmPublic. Specication for a JMS retrieval failure event handler.
Input Parameters
triggerName

String Species the name of the JMS trigger that executed

the trigger service for which the JMS retrieval failure
event occurred.

triggerDestinationIndex

java.lang.Integer Species the index for the destination from

which the JMS trigger receives messages. A JMS trigger
that species a join type can listen for messages from
multiple destinations. The rst destination listed has an
index of 0, the second destination listed has an indices of
1, etc.

webMethods Integration Server Built-In Services Reference Version 9.6

272

Odd Header
Event Folder

deliveryCount

java.lang.Integer Number of times the JMS provider

delivered the message to the JMS trigger at the time the
event occurred.

time

String Date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS

exceptionClass

String Name of the class that caused the failure. This may
be useful to determine programmatically why the error
occurred.

exceptionMessage

String Message contained in the exception.

data

Document A document (IData) containing the JMS message

being processed when the error occurred.
Key

Description

JMSMessage

A document reference (IData) to the

pub.jms:JMSMessage document type.

Output Parameters
None
Usage Notes
A JMS retrieval failure event occurs in the following situations:
A trigger service executed by a JMS trigger throws a non-transient error and the
wa.server.jms.trigger.raiseEventOnException property is set to true (the default).
A trigger service associated with a JMS trigger ends because of a
transient error, all retry aempts have been made, and the JMS trigger
is congured to throw an exception on retry failure. In addition, the
wa.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the
default).
The maximum delivery count from the JMS provider has been met for the message
and the wa.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the
default).
The wa.server.jms.trigger.maxDeliveryCountproperty species the maximum
number of times the JMS provider can deliver a message to Integration Server. The
default is 100. In a JMS message, the property JMSXDeliveryCount species the
number of times the JMS provider delivered the message. Most JMS providers set
this value.

webMethods Integration Server Built-In Services Reference Version 9.6

273

Even Header
Event Folder

While performing exactly-once processing, the connection to the document

history database is unavailable, and transient error handling for the JMS trigger is
congured to Throw exception (non-transacted JMS trigger) or Recover only (transacted
JMS trigger). In addition, the wa.server.jms.trigger.raiseEventOnRetryFailure
property is set to true (the default).
While performing exactly-once processing, the document resolver service ends
with an ISRuntimeException, and transient error handling for the JMS trigger is
congured to Throw exception (non-transacted JMS trigger) or Recover only (transacted
JMS trigger). In addition, the wa.server.jms.trigger.raiseEventOnRetryFailure
property is set to true (the default).
While performing exactly-once processing, the document resolver service
ends with an exception other than an ISRuntimeException. In addition, the
wa.server.jms.trigger.raiseEventOnRetryFailure property is set to true (the default).
Remember to register your event handler with the Event Manager.
Use the wa.server.event.jmsRetrievalError.async server parameter to indicate
whether event handlers for JMS retrieval failure events are invoked synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to JMS retrieval failure events asynchronously. When this
parameter is set to false, Integration Server invokes the event handlers that subscribe to
the JMS retrieval failure events synchronously. The default is true (asynchronous).
See Also
pub.jms:JMSMessage

pub.event:jmsSendErrorEvent
WmPublic. Specication for the JMS delivery failure event handler.
Input Parameters
aliasName

String Name of the JMS connection alias used to send the message to
the JMS provider.

time

String Date and time that the event occurred, in the format yyyy/MM/
dd HH:mm:ss.SS.

data

Document Contents of the JMS message that could not be sent to the
JMS provider.

Output Parameters
None

webMethods Integration Server Built-In Services Reference Version 9.6

274

Odd Header
Event Folder

Usage Notes
Integration Server generates a JMS delivery failure event when a message wrien to the
client side queue cannot be delivered to the JMS provider. When a transient error occurs,
several delivery aempts may have been made.
You might want to create an event handler for a JMS delivery failure event to send
notication or log information about the undelivered JMS message. You can also create
an event handler that aempts to re-send the message to the JMS provider.
Remember to register your event handler with the Event Manager.
Use the wa.server.event.jmsDeliveryFailureError.async server parameter to indicate
whether event handlers for JMS delivery failure events are invoked synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to JMS delivery failure events asynchronously. When this
parameter is set to false, Integration Server invokes the event handlers that subscribe to
the JMS delivery failure events synchronously. The default is true (asynchronous).

pub.event:journal
WmPublic. Specication for journal event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy/
mm/dd hh:mm:ss.ss.

productID

String Name of the product that generated the journal log message
and the event.

majorCode

String Major code of the message.

minorCode

String Minor code of the message.

severity

String Number indicating the severity of the message.

1 Fatal
2 Error
3 Warning
4 Info
5, 6 Debut
7 - 10 Trace

webMethods Integration Server Built-In Services Reference Version 9.6

275

Even Header
Event Folder

defaultMessage

String Default message associated with the major code and minor
code. The actual message may dier from the default message.
For example the default message might be Package WmART
is stopping due to {0}, where {0} is a placeholder for a run-time
parameter. The actual message generated at run time might be
Package WmART is stopping due to ServiceException.

Output Parameters
None.
Usage Notes
Remember to register your even handler using Event Manager orpub.event:addSubscriber.
A journal event handler can have a lter for the major code and minor code of the
generated event. The format of the lter is <majorCode>.<minorCode>. For example,
the following lter species that any journal event with major code of 28 followed by a
minor code of 34 will invoke the event handler: *28.34*
If a journal event is created when synchronously or asynchronously. When this
parameter is set to true, Integration Server writes the following log message
"[ISS.0028.0034I] Package WmISExtDC is stopping " the journal event handler will be
passed the following information in addition to the time value:
productID : ISS
majorCode : 28
minorCode : 34
severity : 4
defaultMessage : Package WmISExtDC is stopping
The wa.server.event.exception.async server parameter indicates whether event
handlers for journal events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe to
journal events asynchronously. When this parameter is set to false, Integration Server
invokes the services that subscribe to the journal events synchronously. The default is
true (asynchronous).

pub.event:journalInfo
WmPublic. Document type for journal event information
Parameters
time

String Date and time that the event occurred, in the format yyyy/
mm/dd hh:mm:ss.ss.

webMethods Integration Server Built-In Services Reference Version 9.6

276

Odd Header
Event Folder

productID

String Name of the product that generated the journal log message
and the event.

majorCode

String Major code of the message.

minorCode

String Minor code of the message.

severity

String Number indicating the severity of the message.

1 Fatal
2 Error
3 Warning
4 Info
5, 6 Debut
7 - 10 Trace

defaultMessage

String Default message associated with the major code and minor
code. The actual message may dier from the default message.
For example the default message might be Package WmART
is stopping due to {0}, where {0} is a placeholder for a run-time
parameter. The actual message generated at run time might be
Package WmART is stopping due to ServiceException.

Usage Notes
If a journal event is created when synchronously or asynchronously. When this
parameter is set to true, Integration Server writes the following log message
"[ISS.0028.0034I] Package WmISExtDC is stopping " the journal event handler will be
passed the following information in addition to the time value:
productID : ISS
majorCode : 28
minorCode : 34
severity : 4
defaultMessage : Package WmISExtDC is stopping
The wa.server.event.exception.async server parameter indicates whether event
handlers for journal events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe to
journal events asynchronously. When this parameter is set to false, Integration Server
invokes the services that subscribe to the journal events synchronously. The default is
true (asynchronous).

webMethods Integration Server Built-In Services Reference Version 9.6

277

Even Header
Event Folder

pub.event:modifySubscriber
WmPublic. Modies the information about a subscription.
Important: The changes you make with this service take eect immediately;
however, they are not made permanent unless you also persist them to
disk with the pub.event:saveEventManagerSettings service. If you do not run
pub.event:saveEventManagerSettings after modifying subscribers, your changes will be lost
when the server is restarted.
Input Parameters
EventType

String Event type that you want the subscription to have:

Alarm Event
Audit Event
Error Event
Exception Event
GD End Event
GD Start Event
JMS Delivery Failure Event
JMS Retrieval Failure Event
Journal Event
Port Status Event
Replication Event
Security Event
Session End Event
Session Expire Event
Session Start Event
Stat Event
Tx End Event
Tx Start Event

Tip: To view the current list of event types, you can execute the
pub.event:getEventTypes service.
gID

String ID of the subscriber that you want to modify. To get the

current list of subscriber IDs, execute thepub.event:getSubscribers
service.

Filter

String Filter that you want subscription to have. Filter is a paernmatching string composed of literal characters, which match a
character exactly, and/or the "*" character, which matches any
sequence of characters. For example:

webMethods Integration Server Built-In Services Reference Version 9.6

278

Odd Header
Event Folder

This pattern string...

Would match...

Any string

M*

Any string that starts with an

uppercase "M."

M*X

Any string that starts with an

uppercase "M" and ends with an
uppercase "X."

The following table shows the aribute that is ltered for each
event type. Note that some event types cannot be ltered.
EventType

Filtered attribute

Alarm Event

Message generated by the alarm

event.

Audit Event

Fully qualied name of the service

that generates the audit event.

Error Event

Error message text for the error that

generates the error event

Exception Event

Fully qualied name of the service

that generates the exception event.

GD End Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

GD Start Event

Fully qualied name of the service

that generates the GD Start Event.

JMS Delivery Failure

Event

Name of the JMS connection alias

used to send the message to the JMS
provider.

JMS Retrieval Failure

Event

Fully qualied name of the JMS

trigger that called the trigger service
for which the error occurred.

webMethods Integration Server Built-In Services Reference Version 9.6

279

Even Header
Event Folder

Journal Event

The major code and minor code of

the message that causes the journal
event.

Port Status Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Replication Event

Name of the package being

replicated.

Security Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Session End Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Session Expire Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Session Start Event

User ID of the user starting the

session or the groups to which the
user belongs. (The lter is applied
to a space delimited list of groups,
composed of group names suxed
with the user's user ID.)
The following examples show how
you might lter session-start events
for various groups and/or user IDs:
To select session starts for any user
in the Administrators group, the
lter would be:
*Administrators*

To select session starts for the user

ID "LRMalley" in the Administrators
group, the lter would be:
*Administrators*LRMalley

To select session starts for the user

ID "LRMalley" in any group, the
lter would be:
*LRMalley

webMethods Integration Server Built-In Services Reference Version 9.6

280

Odd Header
Event Folder

Stat Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Tx End Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Tx Start Event

None. This event type cannot be

ltered. Filter is ignored for this
event type.

Service

String Fully qualied name of the event-handler service that you

want the subscription to specify.

Comment

String Descriptive comment that you want to assign to the

subscription.

Enabled

String Flag specifying the status of the subscription. Must be one of

the following values. Set to:
true to make the subscription active.
false to make the subscription inactive. This is the default.
Note: Although the default value is false, you will generally want
to set Enabled to true to activate the subscription immediately
after it is modied.

Output Parameters
Result

String Flag indicating whether the subscriber was successfully

modied. A value of:
true indicates that the subscriber was updated successfully.
false indicates that the subscriber was not updated (typically
because an invalid subscriber ID was provided in gID ).

See Also
pub.event:addSubscriber
pub.event:deleteSubscriber
pub.event:getSubscribers
pub.event:saveEventManagerSettings

webMethods Integration Server Built-In Services Reference Version 9.6

281

Even Header
Event Folder

pub.event.nerv:eventToDocument
WmPublic. Converts an incoming JMS message into an IS document (pub.event.eda:event).
Input Parameters
JMSMessage

Document A document reference to the IS document of type

pub.jms:JMSMessage.

documentTypeName

String Optional. Fully qualied name of the IS document type

that species the structure to impose on the body of the event.
By specifying a document type, you can identify:
The order and dimensionality of elements.
The prex associated with each namespace in the instance
document.
The document type specied in documentTypeName does not
need to specify every element that will appear in the resulting
document. At a minimum, the document type needs to specify
the elements whose structure you want to explicitly set and the
elements that you want to use in pipeline mapping.
If you do not specify documentTypeName , the structure of the
event body is determined solely by the event document.

Output Parameters
evt:Event

Document A document reference to the pub.event.eda:event document

type which species the structure of an event as a document
(IData Object).

Usage Notes
This service maps various properties from a JMS message to an event document. It also
maps the body from JMS message to the body on the event document.
See Also
pub.jms:JMSMessage
pub.event.eda:event

webMethods Integration Server Built-In Services Reference Version 9.6

282

Odd Header
Event Folder

pub.event.nerv:send
WmPublic. Sends an EDA event to the Network for Event Routing and Variation
(NERV). Integration Server constructs an EDA event using the parameters dened in the
service, and then sends the event to NERV.
Note: NERV is a framework that enables applications to communicate using events. It
uses the Apache Camel integration framework for event routing, ltering, and variation.
By default, NERV uses a Camel component that is congured for JMS as the transport
layer and JNDI destinations as the endpoints. For more information about using NERV
and conguring other providers, see webMethods Event Processing Help.
Input Parameters
documentType
Name

String Optional. Fully qualied name of the IS document type

that species the structure to impose on the body of the event. By
specifying a document type, you can identify:
The order and dimensionality of elements.
The prex associated with each namespace in the instance
document.
When eld names in a document type include a prex
and specify a value for the XML namespace property, the
pub.event.nerv:send service will convert a name/value pair in the
event/body IData with the same prex and name to an XML
element with that prex and with a local name equivalent to the
XML namespace property value.

event

Document A document (IData) containing the event that you want

to publish, including the event header and payload.
Key

Description

header

Document A document containing the

information that you want to set in the event
header.
Key

Description

Start

java.util.date Optional. Start

date and time of the event.
If you do not specify a start
value, the pub.event.nerv:send

webMethods Integration Server Built-In Services Reference Version 9.6

283

Even Header
Event Folder

service uses the current date

and time.
End

java.util.date Optional. End

date and time of the event.

Kind

String Optional. Indicates

whether the event is a
new event (Event) or a
heartbeat event (Heartbeat).
A heartbeat event indicates
the temporal progress of the
stream.
Possible values are Event
and Heartbeat. The default is
Event.

Type

String The name of the event

type for the event.

Version

String Optional. Version of

the event type with which the
event is compatible. An event
should contain a version only
if the event type supports
versioning.
Uses this regular expression
for validation:[0-9]+(.
[0-9]+)*

CorrelationID

String Optional. Unique

identier used to associate
this event with other events.

EventID

String Optional. The unique

identier of the event. This
element can be supplied by
the event producer or can be
system generated.

Priority

String Optional. The priority

of the event to the producer.
The value can be Normal or
High.

webMethods Integration Server Built-In Services Reference Version 9.6

284

Odd Header
Event Folder

body

endpointUris

ProducerID

String Optional. The identier

of the event producer. For
example, this can be an
application identier or a
globally unique identier for
each producer.

UserID

String Optional. The identier

of the user who emied the
event.

CustomHeaders

Document List Optional. Any

other name/value parameters
that should be included in the
header eld of the message.

Document Optional. A document (IData)

containing the payload for the event. If this is
a heartbeat event, do not specify a value for
body .

String Optional. Species the endpoint URIs to which the event

will be sent.
If this parameter is specied, NERV sends the event to the
specied endpoint URIs.
If this parameter is not specied, NERV sends the event to the
default endpoint congured for NERV.

Output Parameters
None.
Usage Notes
The pub.event.nerv:send service sends an event in the form of a Camel message to NERV.
NERV then routes this event to all consumers that have registered a listener for the event
type. You can send a regular EDA event or a heartbeat event for the specied event type
in header/Type . The pub.event.nerv:send service infers whether the event is a regular event
or a heartbeat event based on the presence of the body parameter. To send a heartbeat
event, do not specify a value for the body parameter.
Some aribute values might be inserted into the event by NERV if the event producer
does not supply one. For example, EventID and Start will be assigned if the event
producer does not supply one.
This service replaces pub.event.eda:send, which is deprecated.

webMethods Integration Server Built-In Services Reference Version 9.6

285

Even Header
Event Folder

pub.event:portStatus
WmPublic. Specication for a port status event.
Input Parameters
portStatusInfo

Document List of documents (Data[] objects) containing the

following information for each port.
Key

Description

time

String Date and time that the event occurred, in the

format yyyy/MM/dd HH:mm:ss.SS .

port

String Number for the port.

status

String Status of the port.

protocol

String Type of port (for example, http, https, ftp,

or email).

primary

String Primary port. By default, the webMethods

Integration Server designates an HTTP port at port
5555 as the primary port.

enabled

String Flag indicating whether or not the port is

enabled. Set to:
true to indicate that the port is enabled.
false to indicate that the port is disabled.

Output Parameters
None.

pub.event:portStatusInfo
WmPublic. Document type for port event information.

webMethods Integration Server Built-In Services Reference Version 9.6

286

Odd Header
Event Folder

Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/
dd HH:mm:ss.SS .

port

String Number for the port.

status

String Status of the port.

protocol

String Type of port (for example, http, https, ftp, or email).

primary

String The primary port. By default, the webMethods Integration

Server designates an HTTP port at port 5555 as the primary port.

enabled

String A ag indicating whether or not the port is enabled. A value of:

true indicates that the port is enabled.
false indicates that the port is disabled.

pub.event:reloadEventManagerSettings
WmPublic. Reloads the seings from the event manager's conguration le
(eventcfg.bin) on the server.
Input Parameters
None.
Output Parameters
None.
See Also
pub.event:saveEventManagerSettings

pub.event:replication
WmPublic. Specication for replication event handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

287

Even Header
Event Folder

Input Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS .

action

String Description of the event (such as create or push). The value of

action can be used to maintain separate logs for each action type.

package

String Name of package being replicated.

service

String Fully qualied name of the service that generated the event.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager. When you subscribe an
event handler to a replication event, you can create a lter to specify the package that,
when replicated, will invoke the event handler.
Use the wa.server.event.replication.async server parameter to indicate whether event
handlers for replication events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to replication events asynchronously. When this parameter is set to false, Integration
Server invokes event handlers that subscribe to replication events synchronously. The
default is true (asynchronous).

pub.event:replicationInfo
WmPublic. Document type for replication event information.
Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/dd
HH:mm:ss.SS .

action

String Description of the event (such as create or push). The value of

action can be used to maintain separate logs for each action type.

package

String Name of package being replicated.

service

String Fully qualied name of the service that generated the event.

webMethods Integration Server Built-In Services Reference Version 9.6

288

Odd Header
Event Folder

Usage Notes
Use the wa.server.event.replication.async server parameter to indicate whether event
handlers for replication events are invoked synchronously or asynchronously. When this
parameter is set to true, Integration Server invokes the event handlers that subscribe
to replication events asynchronously. When this parameter is set to false, Integration
Server invokes event handlers that subscribe to replication events synchronously. The
default is true (asynchronous).

pub.event:saveEventManagerSettings
WmPublic. Saves the current subscriber information to the event manager's
conguration le (eventcfg.bin) on the server.
Important: Always run this service after making any permanent changes to subscriber
information (for example, add subscribers, modify subscribers, or delete subscribers).
Otherwise, your changes will be lost the next time the server is restarted.
Input Parameters
None.
Output Parameters
None.
See Also
pub.event:addSubscriber
pub.event:deleteSubscriber
pub.event:modifySubscriber
pub.event:reloadEventManagerSettings

pub.event:security
WmPublic. Specication for security event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format
yyyy/MM/dd HH:mm:ss.SS .

clientID

String IP address of the host from which the request originated.

webMethods Integration Server Built-In Services Reference Version 9.6

289

Even Header
Event Folder

serverID

String IP address of the host on which Integration Server is

running.

userName

String User ID that initiated or performed the security event.

If a value is specied for the clientApplication eld, then
userName identies the OAuth resource owner that permied
the OAuth client application to initiate or perform the security
event.

securityEventType

String Type of security event. Some examples are:

Authentication
Authorization
Certicates
Conguration
JDBC
Pools
Packages
Passwords
Ports
Remote Servers
Services
SSL Web Services

clientApplication

User ID of the OAuth client application that initiated or

performed the security event.
If this eld has a value, the userName eld identies the
OAuth resource owner that permied the OAuth client
application to initiate or perform the security event.

result

String Flag indicating whether the security action completed

successfully. Set to:
True to indicate that the security event completed

successfully.

False to indicate that the security event ended because of

failure.
message

String Indicates what the security action was, irrespective of

whether it was successful or unsuccessful. For example, if a
user was successfully added to Integration Server, the message
would say so. If the event was unsuccessful, this string would
provide a reason or information about the failure, wherever
possible.

webMethods Integration Server Built-In Services Reference Version 9.6

290

Odd Header
Event Folder

Output Parameters
None.
Usage Notes
Use the wa.server.event.security.async server parameter to indicate whether
Integration Server invokes event handlers for security events synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to security events asynchronously. When this parameter is
set to false, Integration Server invokes event handlers that subscribe to security events
synchronously. The default is true (asynchronous).

pub.event:securityInfo
WmPublic. Document type for security event information.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy/
MM/dd HH:mm:ss.SS .

clientID

String IP address of the host from which the request originated.

serverID

String IP address of the host on which Integration Server is

running.

userName

String User ID that initiated or performed the security event.

If a value is specied for the clientApplication eld, then
userName identies the OAuth resource owner that permied
the OAuth client application to initiate or perform the security
event.

securityEventType

String Type of security event. Some examples are:

Authentication
Authorization
Certicates
Conguration
JDBC Pools
Packages
Passwords
Ports
Remote Servers
Services

webMethods Integration Server Built-In Services Reference Version 9.6

291

Even Header
Event Folder

SSL Web Services

clientApplication

String User ID of the OAuth client application that initiated or

performed the security event.
If this eld has a value, the userName eld identies the OAuth
resource owner that permied the OAuth client application to
initiate or perform the security event.
String Flag indicating whether the security action completed
successfully.

result

True indicates that the security event completed successfully.

False indicates that the security event ended because of

failure.

String Indicates what the security action was, irrespective of

whether it was successful or unsuccessful. For example, if a
user was successfully added to Integration Server, the message
would say so. If the event was unsuccessful, this string would
provide a meaningful reason or information about the failure,
wherever possible.

message

Output Parameters
None.
Usage Notes
Use the wa.server.event.security.async server parameter to indicate whether
Integration Server invokes event handlers for security events synchronously or
asynchronously. When this parameter is set to true, Integration Server invokes the
event handlers that subscribe to security events asynchronously. When this parameter is
set to false, Integration Server invokes event handlers that subscribe to security events
synchronously. The default is true (asynchronous).

pub.event:sessionEnd
WmPublic. Specication for sessionEnd event handlers.
Input Parameters
time

String Date and time that the event occurred, in the format yyyy/MM/
dd HH:mm:ss.SS .

sessionID

String Session ID of the service ring the alarm.

webMethods Integration Server Built-In Services Reference Version 9.6

292

Odd Header
Event Folder

rpcs

String Number of service calls the session has performed.

age

String Number of milliseconds the session existed before it ended.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

pub.event:sessionEndInfo
WmPublic. Document type for sessionEnd event information.
Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

sessionID

String Session ID of the service ring the alarm.

rpcs

String Number of service calls the session has performed.

age

String Number of milliseconds the session existed before it ended.

Usage Notes
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

webMethods Integration Server Built-In Services Reference Version 9.6

293

Even Header
Event Folder

pub.event:sessionExpire
WmPublic. Specication for sessionExpire event handlers.
Input Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

sessionID

String Session ID of the service ring the alarm.

rpcs

String Number of service calls the session has performed.

age

String Number of milliseconds the session existed before it expired.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

pub.event:sessionExpireInfo
WmPublic. Document type for sessionExpire event information.
Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

sessionID

String Session ID of the service ring the alarm.

webMethods Integration Server Built-In Services Reference Version 9.6

294

Odd Header
Event Folder

rpcs

String Number of service calls the session has performed.

age

String Number of milliseconds the session existed before it expired.

Usage Notes
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

pub.event:sessionStart
WmPublic. Specication for sessionStart event handlers.
Input Parameters
time

String Date and time that the event occurred. Given in the format
yyyy/MM/dd HH:mm:ss.SS .

sessionID

String ID of the new session.

userid

String User ID that the IS client or developer used to log on to the

webMethods Integration Server.

sessionName

String Name of the new session.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager. When you subscribe an
event handler to a Session Start event, you can create a lter so that only session start
events generated by a specic user or by a member of a specic group invoke the event
handler.
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
webMethods Integration Server Built-In Services Reference Version 9.6

295

Even Header
Event Folder

event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

pub.event:sessionStartInfo
WmPublic. Document type for sessionStart event information.
Parameters
time

String Date and time that the event occurred. Given in the format
yyyy/MM/dd HH:mm:ss.SS .

sessionID

String ID of the new session.

userid

String User ID that the IS client or developer used to log on to the

webMethods Integration Server.

sessionName

String Name of the new session.

Usage Notes
Use the wa.server.event.session.async server parameter to indicate whether Integration
Server invokes event handlers for session events (sessionStart, sessionEnd, and
sessionExpire) synchronously or asynchronously. When this parameter is set to
true, Integration Server invokes event handlers that subscribe to the session events
asynchronously. When this parameter is set to false, Integration Server invokes
event handlers that subscribe to the session events synchronously. The default is true
(asynchronous).

pub.event:stat
WmPublic. Specication for stat event handlers.
Input Parameters
startTime

String Date and time that the event occurred. Given in the
format yyyy/MM/dd HH:mm:ss.SS .

uptime

String Amount of time the server has been up. Given in the
format yyyy/MM/dd HH:mm:ss.SS .

webMethods Integration Server Built-In Services Reference Version 9.6

296

Odd Header
Event Folder

totalMem

String Total amount of used and unused storage available to

the JVM, in kilobytes. For example, a value of 65535 represents
64 megabytes of storage.

freeMem

String Amount of unused storage available to the Integration

Server, in kilobytes. For example, a value of 65535 represents
64 megabytes of storage.

usedMem

String Amount of storage used by the Integration Server,

in kilobytes. For example, a value of 65535 represents 64
megabytes of storage.

freeMemPer

String Percent of total memory unused.

usedMemPer

String Percent of total memory used.

svrT

String Number of services currently running.

svrTMax

String Peak number of servers ever running concurrently.

sysT

String Number of JVM threads running.

sysTMax

String Peak number of threads ever running.

conn

String Number of current sessions.

connMax

String Peak number of concurrent sessions.

reqTotal

String Cumulative total number of services processed.

reqAvg

String Average duration of service.

newReqPM

String New requests per minute.

endReqPM

String End requests per minute.

errSvc

String Number of services completed in error state.

svcRate

String Number of end/start(s) per second.

ssnUsed

String Number of licensed sessions currently active.

webMethods Integration Server Built-In Services Reference Version 9.6

297

Even Header
Event Folder

ssnPeak

String Number of licensed sessions that have ever run

concurrently on the server.

ssnMax

String Maximum number of sessions for which the server is

licensed.

errSys

String Number of unknown errors.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.stat.async server parameter to indicate whether Integration
Server invokes event handlers for statistics events synchronously or asynchronously.
When this parameter is set to true, Integration Server invokes event handlers that
subscribe to the stat event asynchronously. When this parameter is set to false,
Integration Server invokes event handlers that subscribe to stat events synchronously.
The default is true (asynchronous).

pub.event:statInfo
WmPublic. Document type for stat event information.
Parameters
startTime

String Date and time that the event occurred. Given in the
format yyyy/MM/dd HH:mm:ss.SS .

uptime

String Amount of time the server has been up. Given in the
format yyyy/MM/dd HH:mm:ss.SS .

totalMem

String Total amount of used and unused storage available to

the JVM, in kilobytes. For example, a value of 65535 represents
64 megabytes of storage.

freeMem

String Amount of unused storage available to the Integration

Server, in kilobytes. For example, a value of 65535 represents
64 megabytes of storage.

webMethods Integration Server Built-In Services Reference Version 9.6

298

Odd Header
Event Folder

usedMem

String Amount of storage used by the Integration Server,

in kilobytes. For example, a value of 65535 represents 64
megabytes of storage.

freeMemPer

String Percent of total memory unused.

usedMemPer

String Percent of total memory used.

svrT

String Number of services currently running.

svrTMax

String Peak number of servers ever running concurrently.

sysT

String Number of JVM threads running.

sysTMax

String Peak number of threads ever running.

conn

String Number of current sessions.

connMax

String Peak number of concurrent sessions.

reqTotal

String Cumulative total number of services processed.

reqAvg

String Average duration of service.

newReqPM

String New requests per minute.

endReqPM

String End requests per minute.

errSvc

String Number of services completed in error state.

svcRate

String Number of end/start(s) per second.

ssnUsed

String Number of licensed sessions currently active.

ssnPeak

String Number of licensed sessions that have ever run

concurrently on the server.

ssnMax

String Maximum number of sessions for which the server is

licensed.

errSys

String Number of unknown errors.

webMethods Integration Server Built-In Services Reference Version 9.6

299

Even Header
Event Folder

Usage Notes
Use the wa.server.event.stat.async server parameter to indicate whether Integration
Server invokes event handlers for statistics events synchronously or asynchronously.
When this parameter is set to true, Integration Server invokes event handlers that
subscribe to the stat event asynchronously. When this parameter is set to false,
Integration Server invokes event handlers that subscribe to stat events synchronously.
The default is true (asynchronous).

pub.event:txEnd
WmPublic. Specication for txEnd event handlers.
Input Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.tx.async server parameter to indicate whether Integration
Server invokes event handlers for transaction events (txStart and txEnd) synchronously
or asynchronously. When this parameter is set to true, Integration Server invokes
event handlers that subscribe to the txStart or txEnd events asynchronously. When this
parameter is set to false, Integration Server invokes event handlers that subscribe to the
txStart or txEnd events synchronously. The default is true (asynchronous).

pub.event:txEndInfo
WmPublic. Document type for txEnd event information.

webMethods Integration Server Built-In Services Reference Version 9.6

300

Odd Header
Event Folder

Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Usage Notes
Use the wa.server.event.tx.async server parameter to indicate whether Integration
Server invokes event handlers for transaction events (txStart and txEnd) synchronously
or asynchronously. When this parameter is set to true, Integration Server invokes
event handlers that subscribe to the txStart or txEnd events asynchronously. When this
parameter is set to false, Integration Server invokes event handlers that subscribe to the
txStart or txEnd events synchronously. The default is true (asynchronous).

pub.event:txStart
WmPublic. Specication for txStart event handlers.
Input Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Output Parameters
None.
Usage Notes
Remember to register your handler with the Event Manager.
Use the wa.server.event.tx.async server parameter to indicate whether Integration
Server invokes event handlers for transaction events (txStart and txEnd) synchronously
or asynchronously. When this parameter is set to true, Integration Server invokes
event handlers that subscribe to the txStart or txEnd events asynchronously. When this

webMethods Integration Server Built-In Services Reference Version 9.6

301

Even Header
Event Folder

parameter is set to false, Integration Server invokes event handlers that subscribe to the
txStart or txEnd events synchronously. The default is true (asynchronous).

pub.event:txStartInfo
WmPublic. Document type for txStart event information.
Parameters
time

String Date and time that the event occurred. Given in the format yyyy/
MM/dd HH:mm:ss.SS .

TID

String Transaction ID of the service that generated the event.

result

String Status of the transaction.

Usage Notes
Use the wa.server.event.tx.async server parameter to indicate whether Integration
Server invokes event handlers for transaction events (txStart and txEnd) synchronously
or asynchronously. When this parameter is set to true, Integration Server invokes
event handlers that subscribe to the txStart or txEnd events asynchronously. When this
parameter is set to false, Integration Server invokes event handlers that subscribe to the
txStart or txEnd events synchronously. The default is true (asynchronous).

webMethods Integration Server Built-In Services Reference Version 9.6

302

Odd Header
File Folder

8 File Folder
File Access Control Configuration for the pub.file Services .......................................................

304

Parameter Settings .....................................................................................................................

304

Summary of Elements in this Folder .........................................................................................

305

webMethods Integration Server Built-In Services Reference Version 9.6

303

Even Header
File Folder

You use the elements in the le folder to perform operations on the local le system.

File Access Control Configuration for the pub.file Services

The leAccessControl.cnf conguration le in Integration Server_directory\instances
\instance_name \packages\WmPublic\cong directory contains parameters that
Integration Server uses to provide additional validation checks to make the services in
the pub.file folder secure.
Note: If you make any changes to the leAccessControl.cnf, you must reload the
WmPublic package or restart Integration Server for the changes to take eect.

Parameter Settings
The following table shows the parameter seings for the leAccessControl.cnf le:
Parameter

Description

allowedReadPaths

List of directories to which the services in the pub.le folder

have read permission.

allowedWritePaths

List of directories to which the services in the pub.le folder

have write permission.

allowedDeletePaths

List of directories that the services in the pub.le folder can

delete.

When modifying the parameters in the leAccessControl.cnf le, keep the following
points in mind:
Use a semicolon (;) as the delimiter when listing multiple directories. Do not include
spaces between directory paths.
If a le or directory name has a semicolon (;), use backslashes (\\) before the
semicolon while specifying the allowed paths. For example, if the lename is c:/
temp/ab;c.txt, specify it as c:/temp/ab\\;c.txt.
If a directory name is listed, access is allowed to all les in that directory, but not to
the subdirectories.
If a le name is listed, access is allowed only to that le.
For example, the following entry will allow the services in pub.le folder to write to
any le in the c:/wm8/test directory, as well as to the le c:/wm8/test.txt.
allowedWritePaths=C:/wm8/test;C:/wm8/test.txt

webMethods Integration Server Built-In Services Reference Version 9.6

304

Odd Header
File Folder

You can use the wildcard character asterisk (*) to match multiple folders, subfolders,
and les. A single asterisk (*) wildcard can be used to denote single directory names.
Double asterisks (**) can be used to denote multiple les and subfolders in a folder.
For example, the following entry will allow the services in pub.le folder to write to
all the .log les in the rst subdirectory whose name start with 'fatal' in the c:/home/
directory:
allowedWritePaths=C:/home/fatal*/*.log

The following entry will allow the services in pub.le folder to write to all les in all
the subdirectories of c:/home directory:
allowedWritePaths=C:/home/**

The asterisk (*) is the only wildcard character you can use. All other characters are
treated as literals.
You cannot use a wildcard character to match any les in the root directory.
Integration Server ignores the entries that use asterisks to match a le in the root
directory.
For example, Integration Server will ignore the following entry:
allowedWritePaths = **

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.file:bytesToFile

WmPublic. Writes the specied byte array to a le.

pub.file:checkFileExistence

WmPublic. Checks if a specied le exists, and if the le

exists, checks whether the le name represents a le or a
directory.

pub.file:copyFile

WmPublic. Copies a le from one directory to another.

pub.file:deleteFile

WmPublic. Deletes the specied le.

pub.file:getFile

WmPublic. Retrieves a specied le from the local le

system.

pub.file:listFiles

WmPublic. List all the les in a specied directory.

pub.file:moveFile

WmPublic. Moves a le from one directory to another.

webMethods Integration Server Built-In Services Reference Version 9.6

305

Even Header
File Folder

Element

Package and Description

pub.file:readerToFile

WmPublic. Reads data from a java.io.Reader object and

writes it to a le.

pub.file:streamToFile

WmPublic. Writes the data in the InputStream to a le.

pub.file:stringToFile

WmPublic. Writes text to a le.

pub.file:bytesToFile
WmPublic. Writes the specied byte array to a le.
Input Parameters
leName

String The absolute path name of the le to which to write the byte
array.

bytes

Byte[] The byte array to write to the le specied in the lename

parameter.

append

String Optional. Species whether to append or overwrite if the

specied le already exists. The default behavior is to create a new
le if le does not exist or overwrite an existing le if le already
exists.
Set to:
true to append to the le if the le already exists.
false to overwrite the le if the le already exists.

Output Parameters
length

String Number of bytes wrien to the le.

Usage Notes
For security reasons, the pub.file:bytesToFile service checks the input leName parameter
against the list of allowedWritePaths values specied in the FileAccessControl
conguration le. If the input leName is not on the allowed list, Integration Server
throws an exception. For information about conguring the FileAccessControl
conguration le, refer to "File Access Control Conguration for the pub.le Services"
on page 304.

webMethods Integration Server Built-In Services Reference Version 9.6

306

Odd Header
File Folder

pub.file:checkFileExistence
WmPublic. Checks if a specied le exists, and if the le exists, checks whether the le
name represents a le or a directory.
Input Parameters
leName

String The absolute path name of the le to be checked.

Output Parameters
exists

String Indicates whether the specied leName exists or not. A value

of:
true indicates that the specied leName exists.
false indicates that the specied leName does not exist.

isDirectory

String Indicates whether the specied leName is a le or a directory.

true indicates that the specied leName is a directory.
false indicates that the specied leName is a le.

Usage Notes
For security reasons, the pub.file:checkFileExistence service checks the input leName
parameter against the list of allowedReadPaths values specied in the FileAccessControl
conguration le. If the input leName is not on the allowed list, Integration Server
throws an exception. For information about conguring the FileAccessControl
conguration le, refer to "File Access Control Conguration for the pub.le Services"
on page 304.

pub.file:copyFile
WmPublic. Copies a le from one directory to another.
If a le with the same name as the le being copied exists in the targetDirectory , the
pub.file:copyFile service throws an error on execution.
Input Parameters
leName

String The absolute path name of the le to be copied.

webMethods Integration Server Built-In Services Reference Version 9.6

307

Even Header
File Folder

targetDirectory

String Directory to which the le specied in the leName

parameter will be copied.

appendTimestamp

String Optional. Species whether the current timestamp will

be appended to the target lename. Set to:
true to append a timestamp to the target leName in the

yyyyMMddHHmmss format.

false to omit a timestamp from the target leName.

Output Parameters
String The absolute path name of the target le to which the
leName parameter is copied.

targetFileName

Usage Notes
For security reasons, the pub.file:copyFile service checks the input leName against the list
of allowedReadPaths and the input targetDirectory against the list of allowedWritePaths
specied in the FileAccessControl conguration le. If the le name or directory is not
specied in the respective allowed lists, Integration Server throws an exception. For
information about conguring the FileAccessControl conguration le, refer to "File
Access Control Conguration for the pub.le Services" on page 304.

pub.file:deleteFile
WmPublic. Deletes the specied le.
Input Parameters
lename

String The absolute path name of the le to be deleted.

Output Parameters
status

String Species the status of the delete operation. A value of:

true indicates that the deletion succeeded.
false indicates that the deletion failed.

Usage Notes
For security reasons, the pub.file:deleteFile service checks the input leName parameter
against the list of allowedDeletePaths values specied in the FileAccessControl
webMethods Integration Server Built-In Services Reference Version 9.6

308

Odd Header
File Folder

conguration le. If the input leName is not on the allowed list, Integration Server
throws an exception. For information about conguring the FileAccessControl
conguration le, refer to "File Access Control Conguration for the pub.le Services"
on page 304.

pub.file:getFile
WmPublic. Retrieves a specied le from the local le system.
If the le contains an XML document, you can use the services in the XML Folder to
convert it to an XML node.
Input Parameters
lename

String The absolute path name of the le in the local le system (for
example c:\rubicon\document.xml).

loadAs

String Optional. Form in which you want the getFile service to make
the contents of the le available to subsequent services. Set to:
bytes to return the le as a byte array. Use this option if the

contents of the le will be used as input to a service that operates

on whole documents (for example, pub.xml:queryXMLNode). This is
the default.
stream to return the le as an input stream. Use this option

if the contents of the le will be used as input to a service

that can process a document incrementally (for example,
pub.xml:getXMLNodeIterator).
string to return the le as a string.
reader to return the le as a reader.

encoding

String Optional. Character set in which the le is encoded. Specify

an IANA-registered character set (for example, ISO-8859-1). This
information is required to correctly convert the String object to
bytes when performing a get. If no value is specied or if the value
is set to autoDetect, the service uses the default operating system
encoding. If you specify an unsupported encoding, the system
throws an exception.

buerSize

String Optional. Buer size (in bytes) to use if you are loading an
InputStream (that is, loadAs =stream). The default is 4096 bytes.

webMethods Integration Server Built-In Services Reference Version 9.6

309

Even Header
File Folder

Output Parameters
Document Document (IData object) containing the le as a byte[ ],
InputStream, string, or reader. The body parameter will contain
one of the following keys, depending on how the loadAs parameter
was set:

body

Key

Description

bytes

byte[ ]Conditional. Returns le contents in a byte array

if the loadAs parameter is set to bytes.

stream

java.io.InputStream Conditional. Returns le contents

as an InputStream if the loadAs parameter is set to
stream.

reader

java.io.Reader Conditional. Returns le contents as a

reader if the loadAs parameter is set to reader.

string

String Conditional. Returns le contents as a string if the

loadAs parameter is set to string.

Usage Notes
The getFile service does not automatically generate an XML node from the contents of
the le. To generate an XML node, the output from this service must be passed to the
pub.xml:xmlStringToXMLNode service.
See Also
pub.io:close

pub.file:listFiles
WmPublic. List all the les in a specied directory.
The pub.file:listFiles service does not list subdirectories or recursively list subdirectory
contents.
Input Parameters
directory

String[ ] Name of the directory that is to be queried.

webMethods Integration Server Built-In Services Reference Version 9.6

310

Odd Header
File Folder

lter

String Optional. Filter string for the le list (for example, *.java or
EDI*.tx*).

Output Parameters
lelist

String Names of the les in the directory specied in the directory

parameter. Only the le names are returned; not the full path name.

numFiles

String Number of les in the specied directory.

Usage Notes
For security reasons, the pub.file:listFiles service checks the value of the directory parameter
against the list of allowedReadPaths values specied in the FileAccessControl
conguration le. If the specied directory is not on the allowed list, the service throws
an exception. For information about conguring the FileAccessControl conguration
le, refer to "File Access Control Conguration for the pub.le Services" on page 304.

pub.file:moveFile
WmPublic. Moves a le from one directory to another.
If a le with the same name as the leName parameter exists in the target directory, the
pub.file:moveFile service throws an error.
Input Parameters
leName

String The absolute path name of the le to be moved.

targetDirectory

String Name of the directory to which the le specied in the

leName parameter is to be moved.

appendTimeStamp

String Optional. Species whether the current timestamp is

to be appended to the le name after the le is moved to the
target directory. Set to:
false if you do not want to append a timestamp. This is the

default.

true if you want to append a timestamp in the following

format: yyyyMMddHHmmss.

webMethods Integration Server Built-In Services Reference Version 9.6

311

Even Header
File Folder

Output Parameters
status

String Status of the move. A value of:

true indicates that the move was successful.
false indicates that the move failed.

targetFileName

String Fully qualied path of the target le.

Usage Notes
For security reasons, the pub.file:moveFile service checks the input leName parameter
against the list of allowedReadPaths and the input targetDirectory against the list of
allowedWritePaths specied in the FileAccessControl conguration le. If the provided
le name or directory is not specied in the respective allowed lists, Integration
Server throws an exception. For information about conguring the FileAccessControl
conguration le, see "File Access Control Conguration for the pub.le Services" on
page 304.
If the service cannot move the le by using the default move operation in Java, the
service copies the le from the source directory to the destination directory, and then
removes the le from the source directory.

pub.file:readerToFile
WmPublic. Reads data from a java.io.Reader object and writes it to a le.
Input Parameters
leName

String Fully qualied name of the le to which the data is to be

wrien.

reader

java.io.Reader The reader object from which the data is read.

append

String Optional. Species whether to append to or overwrite the

le if it already exists. The default behavior is to create a new le if
the le does not exist or overwrite an existing le if the le already
exists.
Set to:
true to append if the le already exists.
false to overwrite if the le already exists.

webMethods Integration Server Built-In Services Reference Version 9.6

312

Odd Header
File Folder

String Optional. Name of a registered, IANA character set (for

example, ISO-8859-1).

encoding

If you specify an unsupported encoding, the system throws

an exception. If no value is specied or if the encoding is set to
autoDetect, the default operating system encoding is used.
Output Parameters
None.
Usage Notes
For security reasons, the pub.file:readerToFile service checks the input leName parameter
against the list of allowedWritePaths values specied in the FileAccessControl
conguration le. If the input leName is not on the allowed list, the service throws an
exception. For information about conguring the FileAccessControl conguration le,
refer to "File Access Control Conguration for the pub.le Services" on page 304.
The readerToFile service does not automatically close the reader object. To close the reader,
use the pub.io:close service.

pub.file:streamToFile
WmPublic. Writes the data in the InputStream to a le.
Input Parameters
leName

String[] Fully qualied name of the le to be wrien to.

stream

java.io.InputStream The stream from which data is read.

append

String Optional. Species whether to append or overwrite if the

specied le already exists. The default behavior is to create a new le
if the le does not exist or overwrite an existing le if the le already
exists.
Set to:
true to append if the le already exists.
false to overwrite if the le already exists.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

313

Even Header
File Folder

Usage Notes
For security reasons, the pub.file:streamToFile service checks the input leName parameter
against the list of allowedWritePaths values specied in the FileAccessControl
conguration le. If the input leName is not on the allowed list, an exception is thrown.
For information about conguring the FileAccessControl conguration le, refer to "File
Access Control Conguration for the pub.le Services" on page 304.
The streamToFile service does not automatically close the stream object. To close the input
stream, use the pub.io:close service.

pub.file:stringToFile
WmPublic. Writes text to a le.
Input Parameters
leName

String[] Fully qualied name of the le to be wrien to.

data

String Text to be wrien.

append

String Optional. Species whether to append or overwrite if the

specied le already exists. The default behavior is to create a new
le if the le does not exist or overwrite an existing le if the le
already exists.
Set to:
true to append if the le already exists.
false to overwrite if the le already exists.

encoding

String Optional. Name of a registered, IANA character set (for

example, ISO-8859-1).
If you specify an unsupported encoding, the system throws
an exception. If no value is specied or if the encoding is set to
autoDetect, the default operating system encoding is used.

Output Parameters
None.
Usage Notes
For security reasons, the pub.file:stringToFile service checks the input leName parameter
against the list of allowedWritePaths values specied in the FileAccessControl
conguration le. If the input leName is not on the allowed list, an exception is thrown.
webMethods Integration Server Built-In Services Reference Version 9.6

314

Odd Header
File Folder

For information about conguring the FileAccessControl conguration le, refer to "File
Access Control Conguration for the pub.le Services" on page 304.

webMethods Integration Server Built-In Services Reference Version 9.6

315

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

316

Odd Header
Flat File Folder

9 Flat File Folder

Summary of Elements in the Flat File Folder ............................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

318

317

Even Header
Flat File Folder

Use the elements in the Flat File folder to convert between Flat File documents and IS
documents (IData objects), and to manage dictionary entries, entire at le dictionaries,
and at le schemas.

Summary of Elements in the Flat File Folder

The following elements are available in this folder:
Element

Package and Description

pub.flatFile:convertToString

WmFlatFile. Converts an IS
document (IData object) to a at
le document based on the at le
schema that you specify.

pub.flatFile:convertToValues

WmFlatFile. Converts a at le
document to an IS document
(IData object) based on the input
at le schema.

pub.flatFile:FormatService

WmFlatFile. Service that formats

the eld String in a at le schema
or dictionary and ensures that
the value of the String meets the
format restrictions of the format
service.

pub.flatFile:getSupportedEncodings

WmFlatFile. Returns a list of

supported encodings. This service
will only report webMethods
encodings, not Java defaults. That
is, if you do not have converters.jar
installed, it returns null.

pub.flatFile.generate:createDocumentType

WmFlatFile. Creates an IS
document type that denes the
XML representation of a at le
schema.

pub.flatFile.generate:createFFDictionary

WmFlatFile. Creates an empty

at le dictionary. This service
throws an exception is if the at
le dictionary you want to create

webMethods Integration Server Built-In Services Reference Version 9.6

318

Odd Header
Flat File Folder

Element

Package and Description

already exists when the service is
invoked.

pub.flatFile.generate:deleteFFDictionary

WmFlatFile. Deletes a at le
dictionary.

pub.flatFile.generate:deleteFFDictionaryEntry

WmFlatFile. Deletes a single entry

from a at le dictionary.

pub.flatFile.generate:deleteFFSchema

WmFlatFile. Deletes a at le
schema.

pub.flatFile.generate:FFDictionary

WmFlatFile. This IS document

type denes the format to
use when supplying a at le
dictionary or dictionary entry
(in the FFXML variable) and the
format that services return (in the
FFXML variable) when you are
retrieving a at le dictionary or
dictionary entry.

pub.flatFile.generate:FFSchema

WmFlatFile. This IS document

type denes the format to use
when supplying a at le schema
(in the FFXML variable) and the
format that services return (in the
FFXML variable) when you are
retrieving a at le schema.

pub.flatFile.generate:findDependants

WmFlatFile. Returns the names

of all at le schemas and
dictionaries that are dependent on
a given at le dictionary.

pub.flatFile.generate:findReferences

WmFlatFile. Returns the names

of all at le dictionaries that
are referenced by a given at le
dictionary or at le schema.

pub.flatFile.generate:getFFDictionaryAsXML

WmFlatFile. Returns a dictionary

as an XML string.

webMethods Integration Server Built-In Services Reference Version 9.6

319

Even Header
Flat File Folder

Element

Package and Description

pub.flatFile.generate:getFFDictionaryEntryAsXML

WmFlatFile. Returns a single

dictionary entry as an XML string.

pub.flatFile.generate:getFFSchemaAsXML

WmFlatFile. Returns the specied

at le schema as an XML string.

pub.flatFile.generate:listFFDictionaryEntries

WmFlatFile. Lists all entries in a

specied at le dictionary that
are of a specied type.

pub.flatFile.generate:saveXMLAsFFDictionary

WmFlatFile. Creates a at le
dictionary in the Integration Server
namespace by converting the
specied at le dictionary that is
in XML format into a namespace
at le dictionary.

pub.flatFile.generate:saveXMLAsFFSchema

WmFlatFile. Creates a at le
schema in the Integration Server
namespace by converting the
specied at le schema that is in
XML format into a namespace at
le schema.

pub.flatFile.generate:updateFFDictionaryEntryFromXML

WmFlatFile. Updates one or more

entries in a at le dictionary in
the Integration Server namespace.

pub.flatFile:convertToString
WmFlatFile. Converts an IS document (IData object) to a at le document based on the
at le schema that you specify.
By default, this service returns the document as a string, but you can set a ag to
optionally return the document as a byte array instead.
Note: This service does not validate the document.
Input Variables
Values

Document The IData object representing the at le.

webMethods Integration Server Built-In Services Reference Version 9.6

320

Odd Header
Flat File Folder

Schema

String Namespace name of the at le schema to use to convert the

given IS document to a string.

spacePad

String Optional. How to position the records in the at le.

originalError

Value

Description

left

Left justify the records (add blank spaces to the

right of the records) before the records are wrien
to the output. This is the default.

right

Right justify the records (add blank spaces to the

left of the records) before the records are wrien
to the output.

none

No spaces added.

String Whether to create errors in the output.

Value

Description

false

Do not create errors in output.

true

Create errors in output.

If you are upgrading from webMethods Integration Server

version 4.6, to enable left or right justication you must add
the following line to the Integration Server_directory\instances
\instance_name \packages\WmFlatFile\cong\ le:
spacePadJustifies=false

Then, reload the WmFlatFile package so that this conguration

seing will take eect. For details, see the Flat File Schema
Developers Guide or webMethods Service Development Help.
noEmptyTrailing
Fields

String Whether trailing empty elds are to be removed from the

output. Used only with records that have delimited elds.
Value

Description

true

Trailing empty elds will be removed from the

output. For example, if it is set to true, the output
for a record with empty trailing elds looks like

webMethods Integration Server Built-In Services Reference Version 9.6

321

Even Header
Flat File Folder

the following: AAA*01*02! (where ! is used as

segment terminator). This is the default.
false

noEmptyTrailing
SubFields

A eld separator remains to denote an empty

eld. For example, if it is set to false, the output
for a record with empty trailing elds looks like
the following: AAA*01*02********! (where ! is
used as segment terminator).

String Whether trailing empty subelds are to be removed from

the output. Used only with records that have delimited elds.
If no value is specied for the noEmptyTrailingSubFields parameter,
Integration Server uses the value set for the noEmptyTrailingFields
parameter.

delimiters

Value

Description

true

Trailing empty subelds will be removed from the

output.

false

A eld separator remains to denote an empty

subeld.

Document Optional. The separator characters used to construct the

output string. To specify a delimiter, you can specify:
One character or character representation (for example, *, \n for
line terminator, \t for tab)
Hexidecimal value with prex 0X (for example, 0X09, 0X13)
Octal value with prex 0 or decimal value (for example, 009,
013)
Unicode characters (for example, \uXXXX where XXXX
represents the Unicode value of the character)
Value

Description

record

String Character to use to separate records. If you

want to specify the twocharacter carriage return
line feed (CRLF) characters, specify \r\n.

eld

String Character to use to separate elds.

subeld

String Character to use to separate subelds.

webMethods Integration Server Built-In Services Reference Version 9.6

322

Odd Header
Flat File Folder

release

String Character to use to ignore a record , eld , or

subeld delimiter in a eld. If a release character
occurs in a eld or subeld before the delimiter, it
will be prexed with release before being wrien
to the output string .

quotedRelease

String Character to use to ignore a record , eld ,

or subeld delimiter in a eld. If a quoted release
character occurs in a eld or subeld before the
delimiter, it will be prexed with quotedRelease
before being wrien to the output string . The
string is pre- and appended with the quoted
release character.
For example, if * is a delimiter, the eld value
is a*b, and the quoted release character is , the
string appears as a*b.

FormatInfo

Document Any values mapped to the FormatInfo

variable will be passed unmodied to all
format services invoked by convertToString and
convertToValues.

outputFileName

String Optional. If you want the output returned in a le instead

of in the string output variable, provide the name of the le you
want created as a result of this service.

Encoding

String The type of encoding used to write data to the output le.
The default encoding is UTF8.

sortInput

String Optional. Whether you want the service to sort the input
records to match the at le schema specied in Schema . You
should specify true for sortInput if the data in Values is not in the
same order as dened by Schema .
Value

Description

true

You want the service to sort the input records to

match the at le schema.
If you select to sort the input records, note that:
The service will run slower.
All undened records will be sorted after the
dened records.

webMethods Integration Server Built-In Services Reference Version 9.6

323

Even Header
Flat File Folder

The order of the undened records appear in the

nal document is random.
If there are multiple records at the same level with
the same name, the order they appear in the nal
document is random.

returnAsBytes

false

You do not want the service to sort the input

records to match the at le schema. The input
records must match the order of the at le
schema. This is the default.

Value

Description

false

Returns the document as a string. This is the

default.

true

Returns the document as a byte array instead of a

string. This seing is useful (but optional) when
parsing multi-byte encodings.

Output Variables
string

String Data that represents the at le document.

bytes

Object If the input variable returnAsBytes =true, returns the output

as a byte array encoded using the specied encoding. The string
value is not returned.

errorArray

Object String array containing messages pertaining to errors that

occurred during conversion. If no errors are encountered, this
contains a value of null.

Usage Note
When the pub.flatFile:convertToString service executes, the eld that is dened to start after
the end of the xed length record will not be included in the output data if the following
conditions are met:
The at le schema uses a xed length record delimiter.
The at le schema contains a xed position eld that begins beyond the dened
length of the xed length record.
The input to the pub.flatFile:convertToString service contains a value for the xed position
eld that begins beyond the dened length of the xed length record.

webMethods Integration Server Built-In Services Reference Version 9.6

324

Odd Header
Flat File Folder

pub.flatFile:convertToValues
WmFlatFile. Converts a at le document to an IS document (IData object) based on the
input at le schema.
Input Variables
Data

Object The at le input with type of String, InputStream, or

ByteArray.

Schema

String The full name of the at le schema object used to parse the
Data object.

Iterator

Object Optional. An object that encapsulates and keeps track of

the input data during processing. It is used only when the iterate
variable has been set to true.

encoding

String Optional. The encoding of the InputStream passed in to

Data . The default encoding is UTF8.

delimiters

Document Optional. An IData object that contains the segment

terminator and the eld and subeld separators. If the delimiter is
null, it will be located using the information dened in the at le
schema. To specify a delimiter, you can specify:
One character or character representation (for example, *, \n for
line terminator, \t for tab)
Hexidecimal value with prex 0X (for example, 0X09, 0X13)
Octal value with prex 0 or decimal value (for example, 011,

023)

Unicode characters (for example, \uXXXX where XXXX

represents the Unicode value of the character)
The space character.
Important: If you specify one delimiter value, you must specify all
values. Specifying one of these values will override any information
set in the at le schema.
Variable

Description

webMethods Integration Server Built-In Services Reference Version 9.6

325

Even Header
Flat File Folder

record

String Character used to separate records. If

you want to specify the twocharacter carriage
return line feed (CRLF) characters, specify \r\n.

eld

String Character used to separate elds.

subeld

String Character used to separate subelds.

release

String Character used to ignore a record , eld , or

subeld delimiter in a eld. If a release character
occurs in a eld or subeld before the delimiter,
it will be prexed with the release before being
wrien to the output Values .

quotedRelease

String Character to use to ignore a record , eld ,

or subeld delimiter in a eld. If a quoted release
character occurs in a eld or subeld before the
delimiter, it will be prexed with quotedRelease
before being wrien to the output string . The
string is pre- and appended with the quoted
release character.
For example, if * is a delimiter, the eld value
is a*b, and the quoted release character is , the
string appears as a*b.

FormatInfo

iterate

Document Any values mapped to the FormatInfo

variable will be passed unmodied to all
format services invoked by convertToString and
convertToValues.

String Optional. Whether you want to process the input all at one
time.
Value

Description

true

Processes top level records (children of the

document root) in the at le schema one at
a time. After all child records of the top level
record are processed, the iterator moves to
the top level of the next record in the at le
schema, until all records are processed.

false

Processes all input data at one time. This is the

default.

webMethods Integration Server Built-In Services Reference Version 9.6

326

Odd Header
Flat File Folder

createIfNull

skipWhiteSpace

String Optional. Whether to create the IData object if all the elds
are null.
Value

Description

true

No IS document (IData object) will be created if

all the elds are null. This is the default.

false

Always create IS document even though all the

elds are null.

String Optional. Whether white space at the beginning of records

will be ignored.
Note: The xed length record parser ignores skipWhiteSpace ; it
preserves white space.

keepResults

validate

Value

Description

true

Ignore white spaces at the beginning of a record.

This is the default.

false

Record is used as it is identied (useful for

positional data record).

String Optional. Whether to return the parsed data in the Values

output parameter.
Value

Description

true

The parsed Data will be returned in the output

Values . This is the default.

false

Values will not return data. Use this option

when validating the structure of the Data
against the given at le schema.

String Optional. Whether to return error messages that describe how

Data diers from the at le schema.
Value

Description

webMethods Integration Server Built-In Services Reference Version 9.6

327

Even Header
Flat File Folder

returnErrors

true

Do not return error messages describing how

Data diers from the specied at le schema.
This is the default.

false

Return errors describing how the given Data

violates the constraints described in the at le
schema.

String Optional. Whether to return the validation errors. Validation

errors are returned only if validate is set to true.
Value

Description

asArray

Return any validation errors with the Data in

an array called errors . This is the default.

inResults

Return validation errors in the Values object.

both

Return validation errors in both errors and

Values .

maxErrors

String Optional. The maximum number of errors that can be

returned from one record. When the at le parser encounters more
than the maximum number of errors within a record, the parser will
stop parsing and return the parsed data and errors processed up
until that point. Validation errors are returned only if validate is set
to true.

ags

String Optional. Flags that you can set to govern convertToValues

options.
Variable

Description

addRecordCount

String Whether you want the service to add an

additional eld (@recordcount ) to each parsed
record in the resulting IData object (Values ).
The @recordcount eld is used to identify the
record number of each parsed record.
Value

Description

true

The @recordcount eld is added to

each parsed record. This eld contains
the number of the parsed record. The
rst parsed record is 1, the second

webMethods Integration Server Built-In Services Reference Version 9.6

328

Odd Header
Flat File Folder

is 2, etc. If there are records that are

undened data, the count of the
next dened record will reect the
undened data. For example, if the
@recordcount eld for a record is 2
and that record contains 5 undened
records, the @recordcount eld for the
next dened record will be 8.
false

detailedErrors

skipToFirstRecord

The @recordcount eld is not added to

each parsed record. This is the default.

String Whether you want detailed conditional

validation error information. This ag is only
used when validate is true.
Value

Description

true

When a conditional validation error

occurs, the output errors variable will
contain detail information about all
the conditions that were violated. For
more information, see Flat File Schema
Developers Guide.

false

When a conditional validation error

occurs, the service does not provide
detail error information. Conditional
validators report only whether a
condition failed validation with no
additional information about the
conditions that were violated. This is
the default.

String Whether you want the service to wait until

it nds the rst valid record before reporting
invalid records as errors.
Value

Description

true

The service will wait until it nds

the rst valid record before reporting
invalid records as errors. This is the
default.

webMethods Integration Server Built-In Services Reference Version 9.6

329

Even Header
Flat File Folder

false

trimWhitespace

resultAsArray

The service will report invalid records

as errors prior to locating the rst valid
record.

String Whether you want the service to delete

any blank spaces at the beginning of elds, at
the end of elds, or both.
Value

Description

none

The service will not delete any blank

spaces from elds. This is the default.

left

The service will delete all blank spaces

at the beginning of all elds.

right

The service will delete all blank spaces

at the end of all elds.

both

The service will delete all blank spaces

at the beginning and end of all elds.

String Whether you want the service to return

the Values output parameter as an IData[]
that can be mapped to the document types
generated from the schema. An IData[] is a
document List. The resultAsArray parameter is
used only when the iterate input parameter is
set to true.
Value

Description

false

The service returns the Values output

parameter as an IData[] that can
be mapped to the document types
generated from the schema. This is the
default.

true

The service returns the Values output

parameter as an IData object and not as
an IData[].

webMethods Integration Server Built-In Services Reference Version 9.6

330

Odd Header
Flat File Folder

Output Variables
Values

Document The IData object that represents the input at le data.

Iterator

Object Optional. An object that encapsulates and keeps track of

the input records during processing. It is used only when the
iterate variable has been set to true. When all input data has been
processed, the object becomes null. When the Iterator variable is
null, you should exit the LOOP to discontinue processing.

isValid

String Whether at le contains validation errors.

errors

Value

Description

true

The validate input variable was set to true and no errors

were found.

false

The validate input variable was set to true and errors

were found, or the validate input variable was set to
false.

String Optional. An array containing the validation errors, if any,

that were found in Data . For more information about validation
error codes see Flat File Schema Developers Guide.

Usage Note
If you specied a default record denition by which the pub.flatFile:convertToValues service
parses the IS document (IData object), the service displays the resulting recordWithNoID
document as a child of the document above it, in an array.
To display the recordWithNoID record as a child of the root, change the value
of the recWithNoIDLike46 to true in the Integration Server_directory\instances
\instance_name \packages\WmFlatFile\cong\ le and reload the WmFlatFile
package so that this conguration seing will take eect. For more information, see the
Flat File Schema Developers Guide.

pub.flatFile:FormatService
WmFlatFile. Service that formats the eld String in a at le schema or dictionary and
ensures that the value of the String meets the format restrictions of the format service.
Use this specication when you create format services for elds in a at le schema or
dictionary. The format service is invoked for a eld when the pub.flatFile:convertToValues
and pub.flatFile:convertToString services are invoked. You create a format service to format
webMethods Integration Server Built-In Services Reference Version 9.6

331

Even Header
Flat File Folder

the eld String and ensure that the value of the String meets the format restrictions of
the format service. When creating a particular format service for use with the Format
Service property in a at le schema or dictionary, the service you select must implement
the pub.flatFile:FormatService specication (located on its Input/Output tab).
Important: If a particular eld does not have a value (that is, a value is not returned in the
IS document (IData object) for the pub.flatFile:convertToValues service or is not present in the
input data for the pub.flatFile:convertToValues service) the format service assigned to that
eld will not be executed.
Input Variables
value

String The eld value to format.

direction

String Indicates the type of formaing to be applied to the eld.

Specify one of the following:
Value

Description

convertToString This eld is in an outbound document and

needs its internal format converted to its

external format.

convertToValues This eld is in an inbound document and needs

its external format converted to its internal

format.

validate

minLength

String The value of the input parameter validate from the

pub.flatFile:convertToValues service.
true

The value of the convertToValuesvalidate

parameter is true (validate).

false

The value of the convertToValuesvalidate

parameter is false (do not validate). This value
is always false when the value of the direction
parameter is convertToString.

String Enables you to validate the minimum length of a eld. If the

eld is extracted via a Fixed Position Extractor, this is the number
of bytes that are extracted. If the eld is not extracted via the Fixed
Position Extractor and a Length Validator is associated with this
eld, this is the minimum length that will be considered valid.
Otherwise, this parameter will not be present in the pipeline.

webMethods Integration Server Built-In Services Reference Version 9.6

332

Odd Header
Flat File Folder

maxLength

String Enables you to validate the maximum length of a eld. If the

eld is extracted via a Fixed Position Extractor, this is the number
of bytes that are extracted. If the eld is not extracted via the Fixed
Position Extractor and a Length Validator is associated with this
eld, this is the maximum length that will be considered valid.
If the maximum length is unlimited (1) or there is no Length
Validator, this parameter will not be present in the pipeline.

FormatInfo

Document Information that can be used by individual formaing

services. This information can be obtained from one of 3 locations:
convertToString You can specify FormatInfo in addition to the
delimiter information for a call to this service.
convertToValues If delimiter information is explicitly passed into
the convertToValues service, FormatInfo can be specied.
From the UNEDIFACT UNA segment The EDI document type
automatically extracts the decimal separator from the UNA
segment.
The only format services that use this feature are the decimal
formaing services (for implied decimal and decimal formats).
The FormatInfo IS document should contain a string called
DecimalCharacter . If the decimal character is , the number would
be formaed as 100,10 (European format) instead of 100.10, as is
common in the US.
Note: Changes to the data in this object will be reected in all other
format services that are invoked during execution of convertToString
and convertToValues.

Output Variables
formaedValue

String The eld value with appropriate formaing applied.

meetsFormat

String Whether the value could be formaed properly.

Value

Description

true

Indicates that the value could be properly

formaed.

false

Indicates that the value could not be properly

formaed.

webMethods Integration Server Built-In Services Reference Version 9.6

333

Even Header
Flat File Folder

errorMessage

String If meetsFormat is false, this parameter provides a text

message describing the formaing error.

valueToValidate

String The value that will be used by the validator for this eld.
If this value is not present, the value passed in the input variable
value will be validated. This eld is used only for situations in
which the input variable validate is set to true.

maxLength

String Enables you to validate the maximum length of a eld. If the

eld is extracted via a Fixed Position Extractor, this is the number
of bytes that are extracted. If the eld is not extracted via the Fixed
Position Extractor and a Length Validator is associated with this
eld, this is the maximum length that will be considered valid.
If the maximum length is unlimited (1) or there is no Length
Validator, this parameter will not be present in the pipeline.

FormatInfo

Document Information that can be used by individual formaing

services. This information can be obtained from one of 3 locations:
convertToString You can specify FormatInfo in addition to the
delimiter information for a call to this service.
convertToValues If delimiter information is explicitly passed into
the convertToValues service, FormatInfo can be specied.
From the UNEDIFACT UNA segment The EDI document type
automatically extracts the decimal separator from the UNA
segment.
The only format services that use this feature are the decimal
formaing services (for implied decimal and decimal formats).
The FormatInfo IS document should contain a string called
DecimalCharacter . If the decimal character is , the number would
be formaed as 100,10 (European format) instead of 100.10, as is
common in the US.
Note: Changes to the data in this object will be reected in all other
format services that are invoked during execution of convertToString
and convertToValues.

pub.flatFile:getSupportedEncodings
WmFlatFile. Returns a list of supported encodings. This service will only report
webMethods encodings, not Java defaults. That is, if you do not have converters.jar
installed, it returns null.

webMethods Integration Server Built-In Services Reference Version 9.6

334

Odd Header
Flat File Folder

Input Variables
None.
Output Variables
encodings

String List A list of supported encodings.

pub.flatFile.generate:createDocumentType
WmFlatFile. Creates an IS document type that denes the XML representation of a at
le schema.
Input Variables
FlatFileSchema

String The fullyqualied name of the at le schema for which

you want to generate an IS document type.

PackageName

String The name of the Integration Server package in which you

want the created IS document type to be placed.

DocumentType
Name

String The fullyqualied name that you want to assign to the

created IS document type.

Output Variables
None.
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:createFFDictionary
WmFlatFile. Creates an empty at le dictionary. This service throws an exception is if
the at le dictionary you want to create already exists when the service is invoked.

webMethods Integration Server Built-In Services Reference Version 9.6

335

Even Header
Flat File Folder

Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary you want
to create.
PackageName

String The name of the Integration Server package in which you

want the created at le dictionary to be placed.

Output Variables
None.
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:deleteFFDictionary
WmFlatFile. Deletes a at le dictionary.
Before deleting the dictionary, the Integration Server determines if other dictionaries
depend on the dictionary being deleted, and gives the user the option of canceling the
deletion.
Input Variables
FFDictionaryName String The fully qualied name of the at le dictionary that you
want to delete.
Output Variables
deleted

String Whether the at le dictionary was successfully deleted;

deleted will be either true or false.
Value

Description

true

The at le dictionary was successfully deleted.

webMethods Integration Server Built-In Services Reference Version 9.6

336

Odd Header
Flat File Folder

false

The at le dictionary was not successfully deleted.

Usage Note
Before you run this service, you should run the pub.flatFile.generate:findDependants service
to return the names of all at le schemas and dictionaries that are dependent on the
dictionary you are deleting.
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:deleteFFDictionaryEntry
WmFlatFile. Deletes a single entry from a at le dictionary.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that
contains the entry that you want to delete.
EntryName

String The name of the entry that you want to delete.

EntryType

String The type of entry that you are deleting. Specify Record,
Composite, or Field.

Output Variables
deleted

String Whether the at le dictionary entry was successfully

deleted; deleted will be either true or false.
Value

Description

true

The at le dictionary entry was successfully

deleted.

false

The at le dictionary entry was not successfully

deleted.

webMethods Integration Server Built-In Services Reference Version 9.6

337

Even Header
Flat File Folder

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:deleteFFSchema
WmFlatFile. Deletes a at le schema.
Input Variables
FFSchemaName

String The fullyqualied name of the at le schema that you

want to delete.

Output Variables
deleted

String Whether the at le schema was successfully deleted;

deleted will be either true or false.
Value

Description

true

The at le schema was successfully deleted.

false

The at le schema was not successfully deleted.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:FFDictionary
WmFlatFile. This IS document type denes the format to use when supplying a
at le dictionary or dictionary entry (in the FFXML variable) and the format that

webMethods Integration Server Built-In Services Reference Version 9.6

338

Odd Header
Flat File Folder

services return (in the FFXML variable) when you are retrieving a at le dictionary or
dictionary entry.
The structure for this IS document type is dened in the following XML schema:
Integration Server_directory\instances\instance_name \packages\WmFlatFile\pub
\FFGeneration.xsd
Variables
FFDictionary

Document The dictionary entries that you want to add or update.

FFDictionary has the following structure:
RecordDictionary
Entry

Composite
DictionaryEntry

Document List Optional. The dictionary entries for

records that you want to add or update in the at
le dictionary. Leave this null if you do not want
to add or update record entries.
Variable

Description

EntryName

String The name of the record.

RecordDenition

Document The denition of the

record. The information you
specify in a record denition
is the same as the information
that you specify when
creating a at le dictionary
using the Flat File Schema
Editor. For descriptions of the
elds, see webMethods Service
Development Help.

Document List Optional. The dictionary entries for

composites that you want to add or update in the
at le dictionary. Leave this null if you do not
want to add or update composite entries.
Variable

Description

EntryName

String The name of the

composite.

CompositeDenition Document The denition of the

composite. The information
you specify in a composite
denition is the same as

webMethods Integration Server Built-In Services Reference Version 9.6

339

Even Header
Flat File Folder

the information that you

specify when creating a at
le dictionary using the
Flat File Schema Editor. For
descriptions of the elds,
see webMethods Service
Development Help.
FieldDictionary
Entry

Document List Optional. The dictionary entries for

elds that you want to add or update in the at
le dictionary. Leave this null if you do not want
to add or update eld entries.
Variable

Description

EntryName

String The name of the eld.

FieldDenition

Document The denition of the

eld. The information you
specify in a eld denition is
the same as the information
that you specify when
creating a at le dictionary
using the Flat File Schema
Editor. For descriptions of the
elds, see webMethods Service
Development Help.

Usage Notes
If you are using this IS document type to supply a at le dictionary as input
to the pub.flatFile.generate:saveXMLAsFFDictionary, be sure to supply all dictionary
entries. If you are using this IS document type to update an existing dictionary,
provide only the entries that you want to add or update and invoke the
pub.flatFile.generate:updateFFDictionaryEntryFromXML to update the at le dictionary.
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

webMethods Integration Server Built-In Services Reference Version 9.6

340

Odd Header
Flat File Folder

pub.flatFile.generate:FFSchema
WmFlatFile. This IS document type denes the format to use when supplying a at le
schema (in the FFXML variable) and the format that services return (in the FFXML
variable) when you are retrieving a at le schema.
The structure for this IS document type is dened in the following XML schema:
Integration Server_directory\instances\instance_name \packages\WmFlatFile\pub
\FFGeneration.xsd
Variables
FFSchema

Document The at le schema that you want to add or update.

FFSchema has the following structure:
Variable

Description

Delimiters

Document The delimiters used in the at les that

adhere to this at le schema. The information that
you specify for Delimiters corresponds to the data
you specify on the Flat File Definition tab in the Flat
File Schema Editor. For a description of the elds, see
webMethods Service Development Help.

Document
Structure

Document The structure of the at les that adhere to

this at le schema. The information that you specify
for DocumentStructure corresponds to the data you
specify on the Flat File Structure tab in the Flat File
Schema Editor. For a description of the elds, see
webMethods Service Development Help.
Variable

Description

Ordered

String Whether the child records

appear in the at le in the order
they are dened in the at le
schema.

RecordStructure

Document List Denitions of the

records within the at le.
Variable

webMethods Integration Server Built-In Services Reference Version 9.6

Description

341

Even Header
Flat File Folder

Ordered

String Whether
the child
records appear
in the at le
in the order
they are dened
in the at le
schema.

RecordUsage

Document
Information
about how the
record is used,
including either
the dictionary
reference for
this record or
the denition of
the record.

RecordStructure

Document List
Child records of
this record. This
is a recursive
reference to the
RecordStructure
dened in
FFSchema/
DocumentStructure .

RecordParser

Document The type of record parser. In this IS

document, specify only the one variable that
corresponds to the type of record parser to
use. That is, specify one of FixedLengthParser ,
DelimitedParser , VariableLengthParser , or EDIParser .
For DelimitedParser , VariableLengthParser , and
EDIParser , you do not need to specify a value; just
have the variable in the pipeline.

DefaultRecord
Reference

Document Optional. The dictionary name and entry

name that identies the default record for the at le
schema. If you specify a default record, when using
the at le schema to parse a at le schema, the
default record is used for any record that cannot be
recognized.

webMethods Integration Server Built-In Services Reference Version 9.6

342

Odd Header
Flat File Folder

Record
Identier

Document Where to locate the identier to

use to correlate a record in the at le to a
record denition in the at le schema. Specify
either the NthFieldIdentier variable or the
FixedPositionIdentier variable:
Use NthFieldIdentier to identify the eld in the
record (counting from zero) that contains the
identier.
Use FixedPositionIdentier to identify the character
position in the record (counting from zero) where
the record identier is located.

UndenedData
Allowed

String Whether you want the pub.flatFile:convertToValues

service to generate undened data errors when you
use this at le schema to convert a at le to an
IData object.
Specify true if you want to allow undened data
and do not want the pub.flatFile:convertToValues service
to ag undened data errors.
Specify false if you do not want to allow
undened data and you do want the
pub.flatFile:convertToValues service to ag undened
data errors.

Document
Areas

String List Areas for this at le schema. An area is

a way to associate an arbitrary string with a given
record.

FloatingRecord

String Optional. The name of the record that is

dened in the schema as a oating record.
Note: If the oating record has an alternate name,
specify the alternate name.

Description

String Description of the at le schema.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

webMethods Integration Server Built-In Services Reference Version 9.6

343

Even Header
Flat File Folder

pub.flatFile.generate:findDependants
WmFlatFile. Returns the names of all at le schemas and dictionaries that are
dependent on a given at le dictionary.
Input Variables
DictionaryName String The name of the at le dictionary whose dependents you
want to nd.
Output Variables
dependants

Document List The dependent objects and the packages that contain
them.
Variable

Description

packageName String The name of the package that contains the

dependent object.
name

String The name of the dependent object.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:findReferences
WmFlatFile. Returns the names of all at le dictionaries that are referenced by a given
at le dictionary or at le schema.
Input Variables
name

String The name of the at le dictionary or at le schema whose

references you want to nd.

webMethods Integration Server Built-In Services Reference Version 9.6

344

Odd Header
Flat File Folder

Output Variables
references

Document List The referenced objects and the packages that contain
them.
Variable

Description

packageName String The name of the package that contains the

referenced object.
name

String The name of the referenced object.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:getFFDictionaryAsXML
WmFlatFile. Returns a dictionary as an XML string.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that you
want returned as XML.
Output Variables
FFXML

String The returned at le dictionary as an XML string. The

returned XML string conforms to the pub.flatFile.generate:FFDictionary
IS document type.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited

webMethods Integration Server Built-In Services Reference Version 9.6

345

Even Header
Flat File Folder

sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:getFFDictionaryEntryAsXML
WmFlatFile. Returns a single dictionary entry as an XML string.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that
contains the entry that you want returned as XML.
EntryName

String The name of the entry that you want to returned as XML.

EntryType

String The type of entry that you want returned. Specify Record,
Composite, or Field.

Output Variables
FFXML

String The returned at le dictionary entry as an XML string. The

returned XML string conforms to the pub.flatFile.generate:FFDictionary
IS document type.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:getFFSchemaAsXML
WmFlatFile. Returns the specied at le schema as an XML string.
Input Variables
FFSchemaName

String The fullyqualied name of the at le schema that you

want returned as XML.

webMethods Integration Server Built-In Services Reference Version 9.6

346

Odd Header
Flat File Folder

Output Variables
FFXML

String The returned at le schema as an XML string. The returned

XML string conforms to the pub.flatFile.generate:FFDictionary IS
document type.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:listFFDictionaryEntries
WmFlatFile. Lists all entries in a specied at le dictionary that are of a specied type.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that
contains the entries that you want listed.
EntryType

String The type of entries that you want listed. Specify Record,
Composite, or Field.

Output Variables
EntryName

String List The list of returned at le dictionary entries.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

webMethods Integration Server Built-In Services Reference Version 9.6

347

Even Header
Flat File Folder

pub.flatFile.generate:saveXMLAsFFDictionary
WmFlatFile. Creates a at le dictionary in the Integration Server namespace by
converting the specied at le dictionary that is in XML format into a namespace at
le dictionary.
If a at le dictionary with the same name already exists in the Integration Server
namespace, use the pub.flatFile.generate:deleteFFDictionary service to delete the at le
dictionary before invoking this service. This service throws an exception is if a at le
dictionary with the same name already exists when it is invoked.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that you
want to create in the Integration Server namespace.
PackageName

String The name of the Integration Server package in which to save

the at le dictionary.

FFXML

String The at le dictionary (as an XML string) that you want to

create in the Integration Server namespace. The XML string must
conform to the pub.flatFile.generate:FFDictionary IS document type.
Note: To see examples of how to supply the XML string in FFXML
by mapping data from another le, see the samples provided in
the WmFlatFileSamples package. For sample code that shows how
to retrieve the data for FFXML from an XML le in the local le
system, see Flat File Schema Developers Guide.

maxNumOfErrors String Optional. The maximum number of errors that you want
returned. The default is 100.
The service ensures the at le dictionary is valid before saving it
in the Integration Server namespace. The validation occurs in two
stages.
1. Structural validation of the XML.
2. Logical validation of the XML contents.
If structural validation errors occur, the service reports the
structural validation errors, but does not proceed with logical
validation. When the XML string contains no structural validation
errors, the service proceeds with logical validation and reports
any logical validation errors.

webMethods Integration Server Built-In Services Reference Version 9.6

348

Odd Header
Flat File Folder

Output Variables
saved

String Whether the at le dictionary was saved successfully. It

will have one of the following values.
Value

Description

true

The at le dictionary was successfully saved.

false

The at le dictionary was not successfully saved.

Errors

String List Optional. Errors that occurred while aempting to save

the at le dictionary to the Integration Server namespace.

Warnings

String List Optional. Warnings about the at le dictionary that was

created.

Usage Note
Use this service to add a new at le dictionary. Use the
pub.flatFile.generate:updateFFDictionaryEntryFromXML if you want to update one or more entries
in a at le dictionary rather than creating a new at le dictionary.
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:saveXMLAsFFSchema
WmFlatFile. Creates a at le schema in the Integration Server namespace by converting
the specied at le schema that is in XML format into a namespace at le schema.
If a at le schema with the same name already exists in the Integration Server
namespace, use the pub.flatFile.generate:deleteFFSchema service to delete the at le schema
before invoking this service. This service throws an exception is if a at le schema with
the same name already exists when it is invoked.

webMethods Integration Server Built-In Services Reference Version 9.6

349

Even Header
Flat File Folder

Input Variables
FFSchemaName

String The fullyqualied name of the at le schema that you

want to create in the Integration Server namespace.

PackageName

String The name of the Integration Server package in which to save

the at le schema.

FFXML

String The at le schema (as an XML string) that you want to

create in the Integration Server namespace. The XML string must
conform to the pub.flatFile.generate:FFDictionary IS document type.
Note: To see examples of how to supply the XML string in FFXML
by mapping data from another le, see the samples provided in
the WmFlatFileSamples package. For sample code that shows how
to retrieve the data for FFXML from an XML le in the local le
system, see Flat File Schema Developers Guide.

maxNumOfErrors String Optional. The maximum number of errors that you want
returned. The default is 100.
The service ensures the at le schema is valid before saving it in
the Integration Server namespace. The validation occurs in two
stages.
1. Structural validation of the XML.
2. Logical validation of the XML contents.
If structural validation errors occur, the service reports the
structural validation errors, but does not proceed with logical
validation. When the XML string contains no structural validation
errors, the service proceeds with logical validation and reports
any logical validation errors.
Output Variables
saved

String Whether the at le schema was saved successfully. It will

have one of the following values.
Value

Description

true

The at le schema was successfully saved.

false

The at le schema was not successfully saved.

webMethods Integration Server Built-In Services Reference Version 9.6

350

Odd Header
Flat File Folder

Errors

String List Optional. Errors that occurred while aempting to save

the at le schema to the Integration Server namespace.

Warnings

String List Optional. Warnings about the at le schema that was

created.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

pub.flatFile.generate:updateFFDictionaryEntryFromXML
WmFlatFile. Updates one or more entries in a at le dictionary in the Integration Server
namespace.
This service goes through all entries that you specify in the FFXML variable. If an
entry with the same name and type already exists in the at le dictionary, this service
overwrites the existing entry. If the entry does not already exist, this service creates the
entry in the specied at le dictionary.
Input Variables
FFDictionaryName String The fullyqualied name of the at le dictionary that
contains the entries that you are replacing, adding, or both.
FFXML

String The dictionary entries (as an XML string) that you want to
use to replace an existing entry or that you want to add to the at
le dictionary. The XML string in FFXML must conform to the
pub.flatFile.generate:FFDictionary IS document type.
Note: To see examples of how to supply the XML string in FFXML
by mapping data from another le, see the samples provided in
the WmFlatFileSamples package. For sample code that shows how
to retrieve the data for FFXML from an XML le in the local le
system, see Flat File Schema Developers Guide.

maxNumOfErrors String Optional. The maximum number of errors that you want
returned. The default is 100.
The service ensures the at le schema is valid before saving them
in the at le dictionary. The validation occurs in two stages.

webMethods Integration Server Built-In Services Reference Version 9.6

351

Even Header
Flat File Folder

1. Structural validation of the XML.

2. Logical validation of the XML contents.
If structural validation errors occur, the service reports the
structural validation errors, but does not proceed with logical
validation. When the XML string contains no structural validation
errors, the service proceeds with logical validation and reports
any logical validation errors.
Output Variables
saved

String Whether the dictionary entry was saved successfully. It will

have one of the following values.
Value

Description

true

The dictionary entry was successfully saved.

false

The dictionary entry was not successfully saved.

Errors

String List Optional. Errors that occurred while aempting to save

the entry to the at le dictionary.

Warnings

String List Optional. Warnings about the dictionary entry that was
updated or added.

Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support website at
hps://empower.softwareag.com.
sample.flatFile.generateFFSchema:delimited
sample.flatFile.generateFFSchema:fixedLength

webMethods Integration Server Built-In Services Reference Version 9.6

352

Odd Header
Flow Folder

10 Flow Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

354

353

Even Header
Flow Folder

You use the elements in the ow folder to perform debugging and utility-type tasks in a
ow service.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.flow:clearPipeline

WmPublic. Removes all elds from the pipeline.

You may optionally specify elds that should not
be cleared by this service.

pub.flow:debugLog

WmPublic. Writes a message to the server log.

pub.flow:getLastError

WmPublic. Obtains detailed information about

the last exception that was trapped within a ow.

pub.flow:getRetryCount

WmPublic. Retrieves the retry count and the

maximum retry count for a service.

pub.flow:getSession

WmPublic. Inserts the Session object into the

pipeline as a document named $session .

pub.flow:getTransportInfo

WmPublic. Retrieves information about the

protocol from which the current service was
invoked.

pub.flow:invokeService

WmPublic. Dynamically invokes any Integration

Server public service and optionally returns the
output from the invoked service in the pipeline
for pub.flow:invokeService.

pub.flow:restorePipeline

WmPublic. Restores a pipeline previously saved

by pub.flow:savePipeline.

pub.flow:restorePipelineFromFile

WmPublic. Restores a pipeline that was

previously saved to a le.

pub.flow:savePipeline

WmPublic. Saves a pipeline into memory, for

later retrieval with pub.flow:restorePipeline.

webMethods Integration Server Built-In Services Reference Version 9.6

354

Odd Header
Flow Folder

Element

Package and Description

pub.flow:savePipelineToFile

WmPublic. Saves the current pipeline to a le on

the machine running webMethods Integration
Server.

pub.flow:setCustomContextID

WmPublic. Associates a custom value with

an auditing context. This custom value can be
used to search for service audit records in the
webMethods Monitor.

pub.flow:setResponse

WmPublic. Deprecated - Replaced by

pub.flow:setResponse2.

pub.flow:setResponse2

WmPublic. Forces a specied response to

be returned by the webMethods Integration
Server to a calling process (such as a browser or
application server).

pub.flow:setResponseCode

WmPublic. Species the HTTP response code

to be returned by Integration Server to a calling
process (such as a browser or application server).

pub.flow:setResponseHeader

WmPublic. Sets a header eld in the HTTP

response to a calling process (such as a browser
or application server) or in the JMS message that
contains the SOAP response from a web service
invocation.

pub.flow:setResponseHeaders

WmPublic. Sets one or more header elds in

the HTTP response to a calling process (such as
a browser or application server) or in the JMS
message that contains the SOAP response from a
web service invocation.

pub.flow:throwExceptionForRetry

WmPublic. Throws an ISRuntimeException and

instructs the Integration Server to re-execute a
service using the original service input.

pub.flow:tracePipeline

WmPublic. Writes the names and values of all

elds in the pipeline to the server log.

pub.flow:transportInfo

WmPublic. Document type used to return

information about the protocol through which a
service was invoked.

webMethods Integration Server Built-In Services Reference Version 9.6

355

Even Header
Flow Folder

pub.flow:clearPipeline
WmPublic. Removes all elds from the pipeline. You may optionally specify elds that
should not be cleared by this service.
Input Parameters
preserve

String List Optional. Field names that should not be cleared from the
pipeline.

Output Parameters
None.

pub.flow:debugLog
WmPublic. Writes a message to the server log.
Each log message contains a timestamp, a message ID, the function name eld, and
message eld. The following is an example:

Input Parameters
message

String Optional. Text of the message to write to the log.

function

String Optional. Function name, typically an abbreviation used to

identify the source of the message.

level

String Optional. Debug level at which to display this message.

Whether or not Integration Server displays this message depends on
the logging level seing for the 0090 pub Flow services facility. For
example, if you specify Error for this message, but 0090 pub Flow
services facility is congured to display only Fatal errors, this message
will not be displayed. However, if the 0090 pub Flow services logging
facility logging level is set to Warn, this message will be displayed (the
Warn seing displays warning, error, and fatal messages).
Specify one of the following values:

webMethods Integration Server Built-In Services Reference Version 9.6

356

Odd Header
Flow Folder

Specify...

To display the message with these types of messages...

Off

No messages.

Fatal

Fatal messages only. This is the default

Error

Error and fatal messages.

Warn

Warning, error, and fatal messages.

Info

Informational, warning, error, and fatal messages.

Debug

Debug, informational, warning, error, and fatal

messages.

Trace

Trace, debug, informational, warning, error, and fatal

messages.

Output Parameters
None.
Usage Notes
You can control the logging level for ow messages independent of log messages for
other facilities. On the Settings > Logging > Edit screen in Integration Server Administrator,
navigate to facility 0090 pub Flow Services and specify the level of messages that you want
Integration Serverto display for services in the pub.flow folder.
Prior to Integration Server 7.1, Integration Server used a number-based system to set
the level of debug information wrien to the server log. Integration Server maintains
backward compatibility with this system.

pub.flow:getLastError
WmPublic. Obtains detailed information about the last exception that was trapped
within a ow.
An exception is trapped in a ow when a service failure occurs inside a SEQUENCE step
that executes until DONE, or when a service failure occurs inside a REPEAT step that
repeats on FAILURE.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

357

Even Header
Flow Folder

Output Parameters
lastError

Document Information about the last error, translated into the language
used by the Integration Server. The structure of this document is
dened by pub.event:exceptionInfo.

Usage Notes
If this service is not invoked from within a ow service, an exception is thrown.
Each execution of a service (whether the service succeeds or fails) updates the value
returned by getLastError. Consequently, getLastError itself resets the value of lastError .
Therefore, if the results of getLastError will be used as input to subsequent services, map
the value of lastError to a variable in the pipeline.
If a map has multiple transformers, then a subsequent call to getLastError will return the
error associated with the last failed transformer in the map, even if it is followed by
successful transformers.

pub.flow:getRetryCount
WmPublic. Retrieves the retry count and the maximum retry count for a service.
The retry count indicates the number of times the Integration Server has re-executed
a service. For example, a retry count of 1 indicates that the Integration Server tried to
execute the service twice (the initial aempt and then one retry). The maximum retry
count indicates the maximum number of times theIntegration Server can re-execute the
service if it continues to fail because of an ISRuntimeException.
Input Parameters
None.
Output Parameters
retryCount

String The number of times the Integration Server has re-executed

the service.

maxRetryCount

String The maximum number of times the Integration Server can

re-execute the service. A value of -1 indicates that the service is
being invoked by a trigger congured to retry until success.

Usage Notes
Although the pub.flow:getRetryCount service can be invoked at any point in a ow service,
the pub.flow:getRetryCount service retrieves retry information for the service within

webMethods Integration Server Built-In Services Reference Version 9.6

358

Odd Header
Flow Folder

which it is invoked. That is, you can use the pub.flow:getRetryCount service to retrieve
retry information for top-level services or services invoked by a trigger only. The
pub.flow:getRetryCount service does not retrieve retry information for a nested service (a
service that is invoked by another service).
The Integration Server retries a service that is congured to retry if the service uses
the pub.flow:throwISRuntimeException service to catch a transient error and re-throw it as an
ISRuntimeException. The Integration Server will also retry a service wrien in Java if
the service throws an exception using com.wm.app.b2b.server.ISRuntimeException().
For more information about constructing com.wm.app.b2b.server.ISRuntimeExceptions
in Java services, see the webMethods Integration Server Java API Referencefor the
com.wm.app.b2b.server.ISRuntimeException class.
The maximum number of times the Integration Server retries a service depends on the
value of the Max attempts property for the service. If the service is invoked by a trigger,
the retry behavior is determined by the trigger retry properties.
See Also
pub.flow:throwExceptionForRetry

pub.flow:getSession
WmPublic. Inserts the Session object into the pipeline as a document named $session .
Session is useful for associating values with particular clients or users. Once $session
is added to the pipeline, it can be used like any other document in a ow. This permits
more powerful ows that perform work spanning several user requests.
Input Parameters
None.
Output Parameters
$session

Document Information for the current user session. Seing, copying, or

dropping elds within $session is eectively manipulating the Session
object on the server.

pub.flow:getTransportInfo
WmPublic. Retrieves information about the protocol from which the current service was
invoked.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

359

Even Header
Flow Folder

Output Parameters
transport

Document Information about the protocol that invoked the service. The
structure of this document is dened by pub.flow:transportInfo.

Usage Notes
The value of the protocol key in transport indicates which protocol was used to invoked
the service. For example, if the service was invoked via the e-mail protocol, protocol
would be set to email. transport will also contain a document (whose key is protocoldependent) that holds protocol-specic details.
To use this service, rst check the value of the protocol parameter to determine
which protocol had been used. Then, depending on the value of protocol , extract the
appropriate protocol information from transport . See pub.flow:transportInfo for the structure
of the document that holds the protocol details.

pub.flow:invokeService
WmPublic. Dynamically invokes any Integration Server public service and optionally
returns the output from the invoked service in the pipeline for pub.flow:invokeService.
Input Parameters
ifcname

String The ow interface name of the service to be invoked. For example,

pub.math.

svcname

String The name of the service to invoke. For example, addInts.

pipeline

Document Optional. The name of the pipeline for the pub.flow:invokeService

service.
Note: If pipeline is not specied, the invoked service returns the output
parameters in its own pipeline.

Output Parameters
If you specify a value for pipeline , the pub.flow:invokeService service returns the output
parameters dened for the service specied by ifcname and svcname . For example,
pub.flow:invokeService invokes pub.math:addInts as follows:
ifcname = "pub.math"
svcname = "addInts"
pipeline = "mypipeline"
mypipeline.num1 = "100"
mypipeline.num2 = "200"

webMethods Integration Server Built-In Services Reference Version 9.6

360

Odd Header
Flow Folder

In this case, pub.flow:invokeService returns the output parameter as follows:

mypipeline.value = "300"

If you do not specify a value for pipeline , the invoked service returns the output,
notpub.flow:invokeService. For example, if you use pub.flow:invokeService to invoke
pub.math.addInts, the output is returned in the pipeline for pub.math.addInts.
Usage Notes
If the parameters specied by the service invoked by pub.flow:invokeService are not present
or not properly specied, Integration Server issues an exception appropriate for the
invoked service.
Integration Server issues a ServiceException for pub.flow:invokeService if either of the
following is not present in the ow service:
The interface specied by ifcname
The service specied by svcname

pub.flow:restorePipeline
WmPublic. Restores a pipeline previously saved by pub.flow:savePipeline.
Input Parameters
$name

String Name of the saved pipeline. Because multiple pipelines can be

saved, this parameter is necessary to identify the pipeline in memory.
If this value is left null or the name is unknown, an exception will be
thrown.

$merge

String Optional. Flag that indicates whether or not to merge the values in
the existing pipeline with the values in the saved pipeline. Set to:
false to clear the existing pipeline before restoring the saved pipeline.

This is the default.

true to merge the existing pipeline with the saved pipeline. If a eld

exists in the saved pipeline and the existing pipeline, the saved eld
takes precedence.
$remove

String Optional. Flag that indicates whether or not the saved pipeline
will remain in memory after this service is executed. Set to:
false to retain the saved pipeline in memory so that future calls to

restorePipeline with the same $name will still return the saved pipeline.
This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

361

Even Header
Flow Folder

true to remove the saved pipeline from memory after the service

executes.
Output Parameters

The output is dynamic, based on the contents of the saved and existing pipelines.
Usage Notes
After a successful invocation of restorePipeline, the pipeline will contain all elds that were
present immediately before pub.flow:savePipeline was invoked. restorePipeline clears existing
pipeline values unless the optional $merge eld is specied.
When using MTOM streaming for SOAP aachments, messageContext variables and/or
XOPObject elds will not be available in the saved pipeline. A messageContext variable
is used by many pub.soap services to hold the SOAP message on which the service acts.
XOPObject elds are Objects that use the com.wm.util.XOPObject Java wrapper type.
For more information about MTOM Streaming, see the Web Services Developers Guide.
This service is helpful in the interactive development or debugging of an application.
See Also
pub.flow:savePipeline
pub.flow:restorePipelineFromFile

pub.flow:restorePipelineFromFile
WmPublic. Restores a pipeline that was previously saved to a le.
Input Parameters
leName

String Relative path and le name of a le containing a saved pipeline on

the Integration Server. If the le is not found at run time, an exception is
thrown.

merge

String Optional. Flag that determines whether or not to merge the saved
values into the existing pipeline. Set to:
false to replace the existing pipeline with the saved values. This is the

default.

true to merge the saved values into the existing pipeline.

Output Parameters
The output is dynamic, based on the contents of the saved and existing pipelines.

webMethods Integration Server Built-In Services Reference Version 9.6

362

Odd Header
Flow Folder

Usage Notes
This service is helpful in the interactive development or debugging of an application.
In some cases, however, using the Pipeline debug property for the debugging of an
application is more ecient. For more information about the Pipeline debug property,
see webMethods Service Development Help.
Be aware that variables that exist in the saved pipeline but are not dened in the ow
will not appear on the Pipeline tab and, therefore, will not be available for explicit
mapping.
When using MTOM streaming for SOAP aachments, messageContext variables and/or
XOPObject elds will not be available in the saved pipeline. A messageContext variable
is used by many pub.soap services to hold the SOAP message on which the service acts.
XOPObject elds are Objects that use the com.wm.util.XOPObject Java wrapper type.
For more information about MTOM Streaming, see the Web Services Developers Guide.
See Also
pub.flow:savePipelineToFile
pub.flow:restorePipeline

pub.flow:savePipeline
WmPublic. Saves a pipeline into memory, for later retrieval with pub.flow:restorePipeline.
Input Parameters
$name

String Name that will identify the pipeline in memory. An exception will
be thrown if this value is not specied.

Output Parameters
None.
Usage Notes
After a successful invocation of savePipeline, a snapshot of pipeline elds will be saved in
memory under the key provided by $name . Note that because the pipeline is saved to
memory, it will not be available after a server restart.
When using MTOM streaming for SOAP aachments, messageContext variables and/or
XOPObject elds will not be available in the saved pipeline. A messageContext variable
is used by many pub.soap services to hold the SOAP message on which the service acts.
XOPObject elds are Objects that use the com.wm.util.XOPObject Java wrapper type.
For more information about MTOM Streaming, see the Web Services Developers Guide.
This service is helpful in the interactive development or debugging of an application.

webMethods Integration Server Built-In Services Reference Version 9.6

363

Even Header
Flow Folder

See Also
pub.flow:restorePipeline
pub.flow:savePipelineToFile

pub.flow:savePipelineToFile
WmPublic. Saves the current pipeline to a le on the machine running webMethods
Integration Server.
Input Parameters
leName

String Relative path to a le on webMethods Integration Server in which

to save the contents of the pipeline. If the le does not exist, the service
creates it. If the le already exists, the service overwrites it.

Output Parameters
None.
Usage Notes
When using MTOM streaming for SOAP aachments, messageContext variables and/or
XOPObject elds will not be available in the saved pipeline. A messageContext variable
is used by many pub.soap services to hold the SOAP message on which the service acts.
XOPObject elds are Objects that use the com.wm.util.XOPObject Java wrapper type.
For more information about MTOM Streaming, see the Web Services Developers Guide.
This service is helpful in the interactive development or debugging of an application.
In some cases, however, using the Pipeline debug property for the debugging of an
application is more ecient. For more information about the Pipeline debug property,
see webMethods Service Development Help.
The following table shows the data types and classes that this service can write to the
output le if they are included in the pipeline:
For...
Java data
types

pub.flow:savePipelineToFile supports...
byte[]
Date
GregorianCalendar
IData
IData[] (IData list)
String

webMethods Integration Server Built-In Services Reference Version 9.6

364

Odd Header
Flow Folder

For...

pub.flow:savePipelineToFile supports...
String[] (String list)
String[][] (String table)
Vector

Java wrapper
classes

Boolean
Byte
Character
Double
Float
Integer
Long
Short
Single dimension arrays of any of the above

webMethods
classes

MBoolean
MByte
MDouble
MFloat
MInteger
MLong
MShort
Single dimension arrays of any of the above

Object arrays

Any non-array item listed in this table.

See Also
pub.flow:restorePipelineFromFile
pub.flow:savePipeline

pub.flow:setCustomContextID
WmPublic. Associates a custom value with an auditing context. This custom value can
be used to search for service audit records in the webMethods Monitor.

webMethods Integration Server Built-In Services Reference Version 9.6

365

Even Header
Flow Folder

Input Parameters
String Optional. The custom value for the current auditing context.
Specify a value that you want to associate with the auditing
context.

id

Output Parameters
None.
Usage Notes
Each client request creates a new auditing context. The auditing context is the
lifetime of the top-level service. Once the custom context identier is set, Integration
Server includes that value in each service audit record it logs in the current context.
Calls to this service aect audit logging only for the current request.
This service is useful when Integration Server is congured to log to a database.
When the server logs information about a service to the database, it includes the
custom context identier in the service log. Using the webMethods Monitor, you can
use the custom value as search criteria to locate and view all corresponding service
audit records.
If Integration Server is congured to log to a le system, the server writes the custom
context identier with the service audit records to a le. This le is not accessible
with the webMethods Monitor. You cannot use the webMethods Monitor to query
service records when logging to a le.
If this service is invoked without a specied value for id , Integration Server writes
a null value for the custom context identier eld for all subsequent service audit
records that it logs in the current context.

pub.flow:setResponse
WmPublic. Deprecated - Replaced by pub.flow:setResponse2.
Forces a specied response to be returned by the webMethods Integration Server to a
calling process (such as a browser or application server).
Formaing of the response is normally handled by templates, which format values from
the pipeline. If templates are not appropriate for a particular integration scenario, a
response message can be created within the ow and then returned to the caller using
this service.

webMethods Integration Server Built-In Services Reference Version 9.6

366

Odd Header
Flow Folder

Input Parameters
responseString

String Optional. Response to be returned to the caller, specied as a

string.

responseBytes

byte[ ] Optional. Response to be returned to the caller, specied as a

byte array.

string

Deprecated - Replaced by responseString . String Optional. Response to

be returned to the caller, specied as a string.

bytes

Deprecated - Replaced by responseBytes . byte[ ] Optional. Response to

be returned to the caller, specied as a byte array.

response

Deprecated - Replaced by responseString . String Optional. Response to

be returned to the caller, specied as a string.

contentType

String Optional. MIME type of the response data. By default, the

server's response will match the MIME type of the request. This eld
allows this behavior to be overridden.
Note: If you explicitly set this value with Designer, you will see two
choices: text/XML and text/HTML. You are not limited to these two
values. You may either select one of these or type a new value.

encoding

String Optional. Character set in which the response is encoded.

Output Parameters
None.
Usage Notes
Specify responseString or responseBytes , but not both. If you specify both, the
pub.flow:setReponse service uses responseString and ignores responseBytes .
If neither responseString or responseBytes are specied, Integration Server uses the value
of the server conguration parameter wa.server.setReponse.pre82Mode to determine
the order in which to look for and use the deprecated elds.
When wa.server.setResponse.pre82Mode is set to true, Integration Server follows
a precedence order similar to what was available in Integration Server 7.1x and 8.0x.
Specically, Integration Server looks for the deprecated parameters in the following
order and uses the value of the rst parameter that it nds: response , string , bytes
When wa.server.setResponse.pre82Mode is set to false, Integration Server follows
a precedence order similar to what was available in Integration Server 8.2 and later.

webMethods Integration Server Built-In Services Reference Version 9.6

367

Even Header
Flow Folder

Specically, Integration Server looks for the deprecated parameters in the following
order and uses the value of the rst parameter that it nds: string , bytes , response
One possible usage of this service is to create an XML response to an XML request.
A ow that creates an XML document by calling pub.xml:documentToXMLString can use
pub.flow:setResponse to return the XML document to the caller. In your ow, you would
map xmldata (output of pub.xml:documentToXMLString) to responseString and set contentType
to text/xml (inputs to pub.flow:setResponse). Calling pub.flow:setResponse will cause the server
to return the XML document that you've mapped to responseString instead of processing
the pipeline through a template.
Your client might be expecting binary data in the response, such as a JPEG image. In this
case, map a byte array that represents the image to responseBytes and set contentType to
image/jpeg.
Integration Server detects the type of request and sets the Content-Type value to text/
XML (for requests in XML format) or text/HTML (for requests in all other formats). Be
aware that if you specify a value for contentType , Designer will not able to decode or
display output from ows that include this service. This is because your contentType
seing will override the Content-Type value that the Integration Server uses to return
output to Designer. If you use Run to test the ow, Designer will not display any results.
Keep in mind that when returning the processed XML document to the client that
originally submied it, you may need to modify the encoding. Java String objects
are always stored using a Unicode encoding. If your original XML document used
an encoding other than UTF-8 or UTF-16, it will still contain an encoding tag that
indicates what this encoding was. However, if you did not modify the encoding during
document processing, you need to set the encoding parameter when you invoke the
pub.flow:setResponse service. Specically, do one of the following:
Set the encoding parameter to match the tag in the le, or
Set the encoding parameter to "autoDetect" to use the encoding specied in the XML
string encoding tag.

pub.flow:setResponse2
WmPublic. Forces a specied response to be returned by the webMethods Integration
Server to a calling process (such as a browser or application server).
Formaing of the response is normally handled by templates, which format values from
the pipeline. If templates are not appropriate for a particular integration scenario, a
response message can be created within the ow and then returned to the caller using
this service.
Input Parameters
responseString

String Optional. Response to be returned to the caller, specied as

a string.

webMethods Integration Server Built-In Services Reference Version 9.6

368

Odd Header
Flow Folder

responseBytes

byte[ ] Optional. Response to be returned to the caller, specied as

a byte array.

responseStream

java.io.InputStream Optional. Response to be returned to the caller,

specied as an InputStream.

contentType

String Optional. MIME type of the response data. By default, the

server's response will match the MIME type of the request. This
eld allows this behavior to be overridden.
Note: If you explicitly set this value with Designer, you will see two
choices: text/XML and text/HTML. You are not limited to these two
values. You may either select one of these or type a new value.

encoding

String Optional. Character set in which the response is encoded.

Output Parameters
None.
Usage Notes
This service replaces pub.flow:setResponse, which is deprecated.
Specify responseString , responseBytes , or responseStream . If you specify more than one,
the pub.flow:setReponse2 service looks for the parameters in the following order and uses
the rst one that it nds: responseString , responseBytes ,responseStream .
One possible usage of this service is to create an XML response to an XML request.
A ow that creates an XML document by calling pub.xml:documentToXMLString can use
pub.flow:setResponse2 to return the XML document to the caller. In your ow, you would
map xmldata (output of pub.xml:documentToXMLString) to responseString and set contentType
to text/xml (inputs to pub.flow:setResponse2). Calling pub.flow:setResponse2 will cause the
server to return the XML document that you've mapped to responseString instead of
processing the pipeline through a template.
Your client might be expecting binary data in the response, such as a JPEG image. In this
case, map a byte array that represents the image to responseBytes and set contentType to
image/jpeg.
Integration Server detects the type of request and sets the Content-Type value to text/
XML (for requests in XML format) or text/HTML (for requests in all other formats). Be
aware that if you specify a value for contentType , Designer will not able to decode or
display output from ows that include this service. This is because your contentType
seing will override the Content-Type value that the Integration Server uses to return
output to Designer. If you use Run to test the ow, Designer will not display any results.
Keep in mind that when returning the processed XML document to the client that
originally submied it, you may need to modify the encoding. Java String objects
are always stored using a Unicode encoding. If your original XML document used

webMethods Integration Server Built-In Services Reference Version 9.6

369

Even Header
Flow Folder

an encoding other than UTF-8 or UTF-16, it will still contain an encoding tag that
indicates what this encoding was. However, if you did not modify the encoding during
document processing, you need to set the encoding parameter when you invoke the
pub.flow:setResponse2 service. Specically, do one of the following:
Set the encoding parameter to match the tag in the le, or
Set the encoding parameter to "autoDetect" to use the encoding specied in the XML
string encoding tag.

pub.flow:setResponseCode
WmPublic. Species the HTTP response code to be returned by Integration Server to a
calling process (such as a browser or application server).
Input Parameters
String HTTP status code to be returned to the caller.

responseCode

The response codes and phrases are dened in RFC 2616, Section
10. If you provide a value for responseCode that is not listed in RFC
2616, Section 10, you must also provide a value for reasonPhrase .
String Optional. HTTP reason phrase to be returned to the caller. If
no reason is provided, the default reason phrase associated with
responseCode will be used. You must provide a reasonPhrase for any
responseCode that is not listed in RFC 2616, Section 10

reasonPhrase

Output Parameters
None.

pub.flow:setResponseHeader
WmPublic. Sets a header eld in the HTTP response to a calling process (such as a
browser or application server) or in the JMS message that contains the SOAP response
from a web service invocation.
Input Parameters
eldName

String Name of the header eld to set.

eldValue

String Value of the header eld to set.

webMethods Integration Server Built-In Services Reference Version 9.6

370

Odd Header
Flow Folder

Output Parameters
None.
Usage Notes
pub.flow:setResponseHeader sets a single eld in the response header. To set multiple
response header elds, use pub.flow:setResponseHeaders.
You can use pub.flow:setResponse to set the Content-Type of the HTTP header eld.
Content-Type species the format of the service response. For example, to specify
a JSON response, set Content-Type to application/json. For more information
about content types Integration Server supports, see webMethods Integration Server
Administrators Guide.
The following HTTP header elds cannot be set by calling this service or by Integration
Server applications:
Allow
Connection
Content-Length
WWW-Authenticate
Transfer-Encoding
Upgrade
Note: Content-Length can be set with the pub.flow:setResponse service.
Keep the following points in mind when adding headers for a JMS message that
contains a SOAP response:
You can specify custom headers.
You can set some JMS message header elds directly and set others using run-time
properties specic to Integration Server.
You can set JMSType directly. This header name is case-sensitive.
You can set the following headers indirectly using run-time properties:
JMSDeliveryMode, JMSExpiration, and JMSPriority. The following table
identies these properties and indicates the JMS message header elds aected
by each property.
Property Name

Description

jms.deliveryMode
Species the message delivery mode for the

message. Integration Server uses this value to set the

JMSDeliveryMode header.

webMethods Integration Server Built-In Services Reference Version 9.6

371

Even Header
Flow Folder

Property Name

Description
Value

Description

PERSISTENT

Indicates the request message is

persistent.

Default. Indicates the request message is

persistent.

NON_PERSISTENT Indicates the request message is not

persistent.

Indicates the request message is not

persistent.

Note: If the jms.deliveryMode is not one of the above values,

Integration Server ignores the name/value pair and uses the
default value of 2.
jms.timeToLive Length of time, in milliseconds, that the JMS provider

retains the message. A value of 0 means that the message

does not expire.
The JMS provider uses this value to set the JMSExpiration
header in the sent JMS message.
Note: If the jms.timeToLivevalue is not a valid Long,
Integration Server ignores the property and uses the default
value of 0.

jms.priority

Species the message priority. The JMS standard denes

priority levels from 0 to 9, with 0 as the lowest priority and
9 as the highest.
Integration Server uses this value to set the JMSPriority
header.
If the jms.priority value is not a value between 0 to 9,
Integration Server ignores the property and uses the
default value of 4.

You can specify the following JMS-dened properties:

JMSXGroupID
JMSXGroupSeq

webMethods Integration Server Built-In Services Reference Version 9.6

372

Odd Header
Flow Folder

If the value of JMSXGroupSeq is not an String that contains a number,

Integration Server ignores the name/value pair and does not place it in the
message header.
Note: The JMSXGroupID and JMSXGroupSeq names are case-sensitive.
You can set any provider-specic property whose name starts with JMS_ in
eldName . Because the JMS standard reserves the prex JMS_<vendor_name> for
provider-specic properties, Integration Server does not validate the name or value
of this content.
Note: The JMS provider determines which provider-specic properties to accept
and include in the JMS message properties. For more information about providerspecic message properties how the JMS provider handles them, review the JMS
provider documentation.
The lowercase jms. prex is reserved for run-time properties used by Integration
Server. If a header starts with jms. and is not one of the jms. properties dened
by Integration Server, Integration Server ignores the property.
The JMSX prex is reserved for JMS-dened properties. If a header whose name
starts with JMSX is passed into eldName and it is not named JMSXGroupID or
JMSXGroupSeq, Integration Server throws a ServiceException.
You cannot set any of the SOAP over JMS message header properties. These header
names start with SOAPJMS.

pub.flow:setResponseHeaders
WmPublic. Sets one or more header elds in the HTTP response to a calling process
(such as a browser or application server) or in the JMS message that contains the SOAP
response from a web service invocation.
Input Parameters
headers

Document List Contains the header elds to set. Specify the following for
each header that you want to set.
eldName

String Name of the header eld to set.

eldValue

String Value of the header eld to set.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

373

Even Header
Flow Folder

Usage Notes
pub.flow:setResponseHeaders sets one or more elds in the response header. If any of the
elds specied by eldName have already been set, they will be overwrien.
See the Usage Notes for pub.flow:setResponseHeader for more information.

pub.flow:throwExceptionForRetry
WmPublic. Throws an ISRuntimeException and instructs the Integration Server to reexecute a service using the original service input.
Input Parameters
wrappedException

Object Optional. Any exception that you want to include as part

of this ISRuntimeException. This might be the exception that
causes the pub.flow:throwExceptionForRetry service to execute. For
example, if the service aempts to connect to a database and the
connection aempt fails, you might map the exception generated
by the database connection failure to the wrappedException
parameter.

message

String Optional. A message to be logged as part of this exception.

Output Parameters
None.
Usage Notes
Use the pub.flow:throwExceptionForRetry service to handle transient errors that might occur
during service execution. A transient error is an error that arises from a condition that
might be resolved quickly, such as the unavailability of a resource due to network
issues or failure to connect to a database. The service might execute successfully if
the Integration Server waits and then retries the service. If a transient error occurs,
the service can catch this error and invoke pub.flow:throwExceptionForRetry to instruct the
Integration Server to retry the service.
The pub.flow:throwExceptionForRetry service should be used for transient errors only.
Only top-level services or trigger services can be retried. That is, a service can be retried
only when it is invoked directly by a client request or by a trigger. The service cannot be
retried when it is invoked by another service (that is, when it is a nested service).
You can invoke the pub.flow:getRetryCount service to retrieve the current retry count and the
maximum specied retry aempts for a service.

webMethods Integration Server Built-In Services Reference Version 9.6

374

Odd Header
Flow Folder

If the trigger service is wrien in Java, the service can use ISRuntimeException() to
throw an exception and retry the service. For more information about constructing
ISRuntimeExceptions in Java services, see the webMethods Integration Server Java API
Reference for the com.wm.app.b2b.server.ISRuntimeException class.
For information about conguring retry for services or triggers, see webMethods Service
Development Help.
See Also
pub.flow:getRetryCount

pub.flow:tracePipeline
WmPublic. Writes the names and values of all elds in the pipeline to the server log.
Input Parameters
level

String Optional. Debug level at which to write the pipeline. Defaults to

Fatal. If the debug level on the webMethods Integration Server is set to a
value less than this parameter, the pipeline will not be wrien to the server
log.

Output Parameters
None.
Usage Notes
Prior to Integration Server 7.1, Integration Server used a number-based system to set
the level of debug information wrien to the server log. Integration Server maintains
backward compatibility with this system. For more information about logging levels,
see the description of the watt.debug.level parameter in webMethods Integration Server
Administrators Guide.

pub.flow:transportInfo
WmPublic. Document type used to return information about the protocol through which
a service was invoked.
Parameters
protocol

String Name of protocol about which transportInfo contains

information. Will be one of the following values

webMethods Integration Server Built-In Services Reference Version 9.6

375

Even Header
Flow Folder

subprotocol

A value of...

Indicates that...

email

The e-mail protocol was used to invoke the

service. Detailed information is contained in
the email parameter.

filePolling

The le polling protocol was used to

invoke this service. Detailed information is
contained in the lePolling parameter.

ftp

The FTP protocol was used to invoke the

service. Detailed information is contained in
the ftp parameter.

http

The HTTP protocol was used to invoke the

service. Detailed information is contained in
the hp parameter.

jms

The JMS protocol was used to invoke the

service. When a standard JMS trigger or a
SOAP-JMS trigger invokes a service, the
protocol is JMS. Detailed information is
contained in the jms parameter.

String Conditional. Subprotocol for HTTP. For JMS, whether or not the
destinationName value is the actual destination or a lookup.
A value of...

Indicates that...

HTTP

The service was invoked through HTTP.

HTTPS

The service was invoked through HTTPS.

jndi

Integration Server uses JNDI to connect

to the JMS provider. The JMS connection
alias assigned to the JMS trigger species
how Integration Server connects to the JMS
provider.
A value of jndi also indicates that the
destinationName value is a lookup name.

native

Integration Server uses the native

webMethods API to connect to the
webMethods Broker directly. The JMS
connection alias assigned to the JMS trigger

webMethods Integration Server Built-In Services Reference Version 9.6

376

Odd Header
Flow Folder

species how Integration Server connects to

the JMS provider.
A value of native also indicates that the
destinationName value is the name of the
actual destination.
This parameter is returned only when the service was invoked via
HTTP or JMS.
email

Document Conditional. Information about the e-mail transport. This

parameter is returned only if the e-mail transport invoked the service.
Key

Description

to

String List E-mail addresses for the recipients

of the e-mail.

from

String List E-mail addresses for the senders of

the e-mail.

cc

String List Conditional. E-mail addresses

receiving a copy of the e-mail.

bcc

String List Conditional. E-mail addresses

receiving a blind copy of the e-mail.

replyto

String List Conditional. E-mail address to

which replies of this e-mail should be sent

subject

String Subject of the e-mail.

lename

String Conditional. Name of the aached le.

contenype

String Conditional. Content-Type of the

aached le.

content

java.io.InputStream Conditional. Contents of

the aached le.

recvdate

String Conditional. Date the e-mail was

received in String format. recvdate may
be passed as parameter for the java.util.Date
constructor.

webMethods Integration Server Built-In Services Reference Version 9.6

377

Even Header
Flow Folder

sentdate

hp

String Conditional. Date the e-mail was sent

in String format. sentdate may be passed as
parameter for the java.util.Date constructor.

Document Conditional. Information about the hp transport. This

parameter is returned only if the service was invoked via hp.
Key

Description

requestUrl

String URL used by the client to invoke the

service.

query

String Conditional. Query portion of request

URL.

method

String HTTP method used by the client to

request the top-level service. Possible values
are GET, PUT, POST, and DELETE.

requestHdrs

Document Fields in the request header, where

key names represent header eld names and
values represent the header eld values.

ipInfo

Document Information about the hp

socket connection. Contains the following
information:
Key

Description

clientIp

String Optional. IP address

of the client connecting to
this socket. If null, clientIP
is not included in the
output.

clientPort

String Optional. Port

number used by the client
connecting to this socket.
If null, clientPort is not
included in the output.

localIp

String Local IP address for

this socket connection to
client.

webMethods Integration Server Built-In Services Reference Version 9.6

378

Odd Header
Flow Folder

ftp

localPort

String Local port number

for this socket connection
to client.

remoteIp

String Remote IP address

for this socket connection
to client.

remotePort

String Remote port

number for this socket
connection to client.

Document Conditional. Information about the ftp transport. This

parameter is returned only if the ftp transport invoked the service.
Key

Description

lename

String Name of le that was put into the

service directory.

mimetype

String Conditional. Content type of the

le (for example, text/xml, text/
plain, or image/jpeg). The server
determines content type based on the
extension of the le and the extension's
corresponding content type dened in
Integration Server_directory\instances
\instance_name \lib\mime.types.

ipInfo

Document Information about the FTP

socket connection. Contains the following
information:
Key

Description

localIp

String Local IP address for

this socket connection to
client.

localPort

String Local port number

for this socket connection
to client.

webMethods Integration Server Built-In Services Reference Version 9.6

379

Even Header
Flow Folder

lePolling

jms

remoteIp

String Remote IP address

for this socket connection
to client.

remotePort

String Remote port

number for this socket
connection to client.

Document Conditional. Information about the le polling transport.

Returned only if the le polling transport invoked the service.
Key

Description

lename

String Fully qualied name of the le

submied to the le polling listener.

originalFilename

String Name of the le when it was submied

to the le polling listener.

contenype

String Conditional. Content type of the

le (for example, text/xml, text/
plain, or image/jpeg). The server
determines content type based on the
extension of the le and the extension's
corresponding content type dened in
Integration Server_directory\instances
\instance_name \lib\mime.types.

length

String The original le length in bytes.

lastModied

java.util.Date Java date object indicating when

the original le was last modied.

Document Conditional. Information about the JMS transport. This

parameter is returned only if the JMS transport invoked the service.
Key

Description

connectionAliasName

String Name of the JMS connection alias used

by the JMS trigger to retrieve the message.

triggerName

String Fully qualied name of the JMS trigger

that retrieved the JMS message that resulted
in invocation of the service.

webMethods Integration Server Built-In Services Reference Version 9.6

380

Odd Header
Flow Folder

destinationName

String Name or lookup name of the

destination from which the message that
invoke the service was received.
When the subprotocol is jndi, the
destinationName value is the lookup name
of the destination on the JNDI provider.
When the subprotocol is native, the
destinationName value is the name of the
destination at the webMethods Broker.

destinationType

String Type of destination from which the

JMS trigger received the message. The
destination type for the JMS trigger specied
in triggerName subscribes determines the
destinationType value.
destinationType will be one of the following:
QUEUE indicates the destination is a queue.
TOPIC indicates the destination is a topic.

requestHdrs

Document Fields in the request header, where

key names represent header eld names and
values represent header eld values.

Usage Notes
A document with this structure is output by the pub.flow:getTransportInfo service.

webMethods Integration Server Built-In Services Reference Version 9.6

381

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

382

Odd Header
Hashtable Folder

11 Hashtable Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

384

383

Even Header
Hashtable Folder

This folder contains services that you can use to create, update, and obtain information
about the hashtable.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.hashtable:containsKey

WmPublic. Checks for the existence of a

hashtable element.

pub.hashtable:createHashtable

WmPublic. Creates a hashtable object.

pub.hashtable:get

WmPublic. Gets the value for a specied key in

the hashtable.

pub.hashtable:listKeys

WmPublic. Lists all the keys stored in the

hashtable.

pub.hashtable:put

WmPublic. Adds a key/value pair in the

hashtable.

pub.hashtable:remove

WmPublic. Removes a key/value pair from the

hashtable.

pub.hashtable:size

WmPublic. Gets the number of elements in the

hashtable.

pub.hashtable:containsKey
WmPublic. Checks for the existence of a hashtable element.
Input Parameters
hashtable

java.util.Hashtable Hashtable in which to check for the existence of a

hashtable element.

key

String Hashtable element to be checked for.

webMethods Integration Server Built-In Services Reference Version 9.6

384

Odd Header
Hashtable Folder

Output Parameters
containsKey

String Indicates whether the specied hashtable element exists. A

value of:
true indicates that the element exists.
false indicates that the element does not exist.

pub.hashtable:createHashtable
WmPublic. Creates a hashtable object.
Input Parameters
None.
Output Parameters
hashtable

java.util.Hashtable The new hashtable object.

pub.hashtable:get
WmPublic. Gets the value for a specied key in the hashtable.
Input Parameters
hashtable

java.util.Hashtable Hashtable from which to retrieve the specied value.

key

String Key of the hashtable element whose value is to be retrieved.

Output Parameters
value

Object Value of the input hashtable element.

pub.hashtable:listKeys
WmPublic. Lists all the keys stored in the hashtable.

webMethods Integration Server Built-In Services Reference Version 9.6

385

Even Header
Hashtable Folder

Input Parameters
hashtable

java.util.Hashtable Hashtable from which the keys are to be listed.

Output Parameters
keys

String[] List of keys stored in the input hashtable.

pub.hashtable:put
WmPublic. Adds a key/value pair in the hashtable.
Input Parameters
hashtable

java.util.Hashtable Hashtable to which the key/value pair is to be added.

key

String Key of the element to be added to the hashtable.

value

Object Value of the element to be inserted into the hashtable.

Output Parameters
hashtable

java.util.Hashtable Hashtable object after the insertion of the key/value

pair.

pub.hashtable:remove
WmPublic. Removes a key/value pair from the hashtable.
Input Parameters
hashtable

java.util.Hashtable Hashtable from which to remove the key/value pair.

key

String Key of the hashtable element to be removed.

value

Object Value of the hashtable element to be removed.

webMethods Integration Server Built-In Services Reference Version 9.6

386

Odd Header
Hashtable Folder

Output Parameters
hashtable

java.util.Hashtable Hashtable object after the key/value pair is removed.

value

Object Value of the hashtable element that was removed. Returns null
if the input key is not found in the hashtable.

pub.hashtable:size
WmPublic. Gets the number of elements in the hashtable.
Input Parameters
hashtable

java.util.Hashtable Hashtable from which the number of elements stored

in it is to be retrieved.

Output Parameters
size

String Number of elements in the hashtable.

webMethods Integration Server Built-In Services Reference Version 9.6

387

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

388

Odd Header
IO Folder

12 IO Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

390

389

Even Header
IO Folder

You use the elements in the io folder to convert data between byte[ ] , characters, and
InputStream representations. The io folder contains services for reading and writing
bytes, characters, and streamed data to the le system.
These services behave like the corresponding methods in the java.io.InputStream class.
For more information about InputStreams, see the Java documentation.

Summary of Elements in this Folder

Note: The services in this folder may only be invoked by other services on Integration
Server. Streams cannot be passed between clients and Integration Server, so these
services will not execute if they are invoked from a client.
The following elements are available in this folder:
Element

Package and Description

pub.io:bytesToStream

WmPublic. Converts a byte[ ] to

java.io.ByteArrayInputStream.

pub.io:close

WmPublic. Closes an InputStream or a reader object

and releases the resources.

pub.io:createByteArray

WmPublic. Creates a byte array of the specied

length.

pub.io:mark

WmPublic. Marks the current position in the

InputStream or reader object.

pub.io:markSupported

WmPublic. Enables you to test whether your

InputStream or reader object supports the mark and
reset operations.

pub.io:read

WmPublic. Reads a specied number of bytes from

the InputStream and stores them into a buer.

pub.io:readAsString

WmPublic. Reads the data from a reader object and

returns the contents as a string.

pub.io:readerToString

WmPublic. Reads the data from a reader object and

converts it to a string.

webMethods Integration Server Built-In Services Reference Version 9.6

390

Odd Header
IO Folder

Element

Package and Description

pub.io:reset

WmPublic. Repositions the InputStream or the reader

object to the position at the time the pub.io:mark service
was last invoked on the stream.

pub.io:skip

WmPublic. Skips over and discards the specied

number of bytes or characters from the input stream
or a reader object.

pub.io:streamToBytes

WmPublic. Creates a byte[ ] from data that is read

from an InputStream.

pub.io:streamToReader

WmPublic. Converts a java.io.InputStream to a

java.io.Reader object.

pub.io:streamToString

WmPublic. Creates a string from data that is read

from an InputStream.

pub.io:stringToReader

WmPublic. Converts a string object to a

java.io.StringReader object.

pub.io:stringToStream

WmPublic. Converts a string to a byte stream.

pub.io:bytesToStream
WmPublic. Converts a byte[ ] to java.io.ByteArrayInputStream.
Input Parameters
bytes

byte[ ] The byte array to convert.

length

String Optional. The maximum number of bytes to read and

convert. If length is not specied, the default value for this
parameter is the length of the input byte array.

oset

String Optional. The oset into the input byte array from which
to start converting. If no value specied, the default value is
zero.

webMethods Integration Server Built-In Services Reference Version 9.6

391

Even Header
IO Folder

Output Parameters
stream

java.io.ByteArrayInputStream An open InputStream created from

the contents of the input bytes parameter.

Usage Notes
This service constructs stream from the byte array using the constructor
ByteArrayInputStream(byte[ ]). This constructor does not make a copy of the byte array,
so any changes to bytes will be reected in the data read from the stream.

pub.io:close
WmPublic. Closes an InputStream or a reader object and releases the resources.
Input Parameters
inputStream

java.io.InputStream Optional. An open InputStream.

Note: You can use either inputStream or reader to specify the
input object. If both the input parameters are provided, then
both the objects will be closed.

reader

java.io.Reader Optional. An open reader object.

Output Parameters
None.
Usage Notes
If the InputStream is already closed, invoking this service has no eect. However,
leaving an InputStream open may cause errors that are not recoverable until Integration
Server is shut down. Use the pub.io:close service to explicitly close the input stream when
a service leaves it open. For example, pub.file:getFile and pub.client.ftp:get leave the input
stream open in the pipeline.

pub.io:createByteArray
WmPublic. Creates a byte array of the specied length.

webMethods Integration Server Built-In Services Reference Version 9.6

392

Odd Header
IO Folder

Input Parameters
length

String The length of the byte array to be created.

Output Parameters
bytes

Object The new byte array.

Usage Notes
The pub.io:read service reads data from an InputStream into a byte array. You can use this
service to create the byte array. Invoking this service is the equivalent of the Java code
new byte[length].

pub.io:mark
WmPublic. Marks the current position in the InputStream or reader object.
A subsequent call to pub.io:reset repositions this stream at the last marked position.
Marking and respositioning the input stream allows subsequent service calls to re-read
the same bytes.
Input Parameters
stream

java.io.InputStream Optional. The InputStream.

Note: You can use either stream or reader to specify the input
object. If both stream and reader input parameters are provided,
then both the objects will be marked.

reader

java.io.Reader Optional. The reader object.

limit

String The maximum number of bytes that can be read before

the mark position becomes invalid. If more than this number
of bytes are read from the stream after the pub.io:mark service is
invoked, the pub.io:reset service will have no eect.

Output Parameters
stream

java.io.InputStream Conditional. The InputStream. Returned

only if the input parameter is stream .

webMethods Integration Server Built-In Services Reference Version 9.6

393

Even Header
IO Folder

reader

java.io.Reader Conditional. The reader object. Returned only if

the input parameter is reader .

Usage Notes
If the InputStream does not support the mark operation, invoking this service has no
eect.
Either of the optional input parameters, stream or reader , is required.

pub.io:markSupported
WmPublic. Enables you to test whether your InputStream or reader object supports the
mark and reset operations.
Input Parameters
stream

java.io.InputStream Optional. The InputStream.

Note: You can use either stream or reader to specify the input
object. If both stream and reader input parameters are provided,
then the stream input parameter is ignored.

reader

java.io.Reader Optional. The reader object.

Output Parameters
stream

java.io.InputStream Conditional. The InputStream. Returned

only if the input parameter is stream .

supported

String Indicates whether the stream supports the mark and

reset operations. A value of:
true indicates that the InputStream supports the mark and

reset operations.

false indicates that the InputStream does not support the

mark and reset operations.

reader

java.io.ReaderConditional. The reader object. Returned only if

the input parameter is reader .

Usage Notes
Either of the input parameters, stream or reader , is required.

webMethods Integration Server Built-In Services Reference Version 9.6

394

Odd Header
IO Folder

pub.io:read
WmPublic. Reads a specied number of bytes from the InputStream and stores them
into a buer.
Input Parameters
stream

Object The InputStream. Object from which the service is to

read bytes.

oset

String Optional The oset into the byte array in the buer to
which the data is wrien. If no value is supplied, this defaults
to 0.

length

String Optional. The maximum number of bytes to read from

the InputStream. If no value is supplied, the default is the
length of buer .
If the value supplied for length is greater than the length of
buer , an exception will be thrown.

buer

Object The buer into which data is wrien. This is a byte

array, which can be created from a Flow service by invoking
pub.io:createByteArray.

Output Parameters
stream

Object The InputStream. If any bytes were read from the

stream, the stream is repositioned after the last byte read.

buer

Object The buer into which data was wrien.

bytesRead

String The number of bytes read from the InputStream and

copied to buer . If there is no more data because the end of the
stream has been reached, bytesRead will be -1.

pub.io:readAsString
WmPublic. Reads the data from a reader object and returns the contents as a string.

webMethods Integration Server Built-In Services Reference Version 9.6

395

Even Header
IO Folder

Input Parameters
reader

java.io.Reader The reader object.

length

String The maximum number of characters to read from the

input reader object.

Output Parameters
reader

java.io.Reader The reader object.

lengthRead

String The number of characters read from the input reader

object. If there is no more data because the end of the stream
has been reached, lengthRead will be -1.

value

String The data read from the reader object, or null if end of
stream has been reached.

Usage Notes
The readAsString service does not automatically close the reader object. To close the reader,
use the pub.io:close service.

pub.io:readerToString
WmPublic. Reads the data from a reader object and converts it to a string.
Input Parameters
reader

java.io.Reader The reader object.

Output Parameters
string

String Data read from the reader object.

Usage Notes
The readerToString service does not automatically close the reader object. To close the
reader, use the pub.io:close service.

webMethods Integration Server Built-In Services Reference Version 9.6

396

Odd Header
IO Folder

pub.io:reset
WmPublic. Repositions the InputStream or the reader object to the position at the time
the pub.io:mark service was last invoked on the stream.
Input Parameters
stream

java.io.InputStream Optional. The InputStream.

Note: You can use either stream or reader to specify the input
object. If both stream and reader input parameters are provided,
then both the objects will be reset.

reader

java.io.Reader Optional. The reader object.

Output Parameters
stream

java.io.InputStream Conditional. The InputStream. Returned

only if the input parameter is stream .

reader

java.io.Reader Conditional. The reader object. Returned only if

the input parameter is reader .

Usage Notes
If the InputStream does not support the reset operation, invoking this service has no
eect.
Either of the input parameters, stream or reader , is required.

pub.io:skip
WmPublic. Skips over and discards the specied number of bytes or characters from the
input stream or a reader object.
Input Parameters
stream

java.io.InputStream Optional. The InputStream.

Note: You can use either stream or reader to specify the input
object. If both stream and reader input parameters are provided,
then the stream and reader object data will be skipped.

webMethods Integration Server Built-In Services Reference Version 9.6

397

Even Header
IO Folder

reader

java.io.Reader Optional. The reader object.

length

String The number of bytes or characters to skip.

Output Parameters
stream

java.io.InputStream Conditional. The InputStream. Returned

only if the input parameter is stream .

reader

java.io.Reader Conditional. The reader object. Returned only if

the input parameter is reader .

bytesSkipped

String Conditional. The actual number of bytes that were

skipped. Returned only if the input parameter is stream .

charactersSkipped

String Conditional. The number of characters that were

skipped. Returned only if the input parameter is reader .

Usage Notes
Thepub.io:skip service uses the uses the Java methodInputStream.skip, which might
skip some smaller number of bytes, possibly zero (0). This happens due to conditions
such as reaching the end of le before n bytes have been skipped. For more information
about the InputStream.skip method, see the Java documentation on the InputStream
class.
Either of the optional input parameters, stream or reader , is required.
If both stream and reader input parameters are specied and if an exception occurs
during the stream object usage, then the operations are not performed on the reader
object also.

pub.io:streamToBytes
WmPublic. Creates a byte[ ] from data that is read from an InputStream.
Input Parameters
stream

java.io.InputStream The InputStream that you want to convert.

Output Parameters
bytes

byte[ ]The bytes read from stream .

webMethods Integration Server Built-In Services Reference Version 9.6

398

Odd Header
IO Folder

Usage Notes
This service reads all of the bytes from stream until the end of le is reached, and then it
closes the InputStream.

pub.io:streamToReader
WmPublic. Converts a java.io.InputStream to a java.io.Reader object.
Input Parameters
inputStream

java.io.InputStream The InputStream to convert to a reader

object.

encoding

String Optional. Name of a registered, IANA character set

(for example, ISO-8859-1). If you specify an unsupported
encoding, the system throws an exception. If no value is
specied or if the encoding is set to autoDetect, the default
operating system encoding is used.

Output Parameters
reader

java.io.Reader The reader object read from inputStream .

pub.io:streamToString
WmPublic. Creates a string from data that is read from an InputStream.
Input Parameters
inputStream

java.io.InputStream The InputStream to convert to a string.

encoding

String Optional. Name of a registered, IANA character set

(for example, ISO-8859-1). If you specify an unsupported
encoding, the system throws an exception. If no value is
specied or if the encoding is set to autoDetect, the default
operating system encoding is used.

webMethods Integration Server Built-In Services Reference Version 9.6

399

Even Header
IO Folder

Output Parameters
string

String Data read from inputStream and converted to a string.

pub.io:stringToReader
WmPublic. Converts a string object to a java.io.StringReader object.
Input Parameters
string

String The string to convert to a StringReader object.

Output Parameters
reader

java.io.StringReader The StringReader object.

pub.io:stringToStream
WmPublic. Converts a string to a byte stream.
Input Parameters
string

String The string object to be converted.

encoding

String Optional. Name of a registered, IANA character set

(for example, ISO-8859-1). If you specify an unsupported
encoding, the system throws an exception. If no value is
specied or if the encoding is set to autoDetect, the default
operating system encoding is used.

Output Parameters
inputStream

java.io.ByteArrayInputStream An open InputStream created from

the contents of string .

webMethods Integration Server Built-In Services Reference Version 9.6

400

Odd Header
JDBC Folder

13 JDBC Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

402

401

Even Header
JDBC Folder

You use the elements in the JDBC folder to obtain information about Integration Server
JDBC pools.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.jdbc:getPoolInfo

WmPublic. Returns run-time information about the JDBC

pool associated with a specied functional alias.

pub.jdbc:getPoolInfo
WmPublic. Returns run-time information about the JDBC pool associated with a
specied functional alias.
Input Parameters
functionalAlias

String Name of the Integration Server functional alias for which

you want to obtain JDBC information.

getConnectionWait

String Optional. Number of milliseconds the service will

wait to obtain a connection to a JDBC connection pool. The
default is 10 seconds (10000 milliseconds). If a connection is
not obtained within this time, the service ends with a status of
fail.

Output Parameters
minConnections

String The minimum number of connections the pool can have.

maxConnections

String The maximum number of connections the pool can have.

totalConnections

String The total number of connections currently in the pool.

This number includes connections that are already in use and
connections that are available for use.

availableConnections

String The number of connections that are available for use.

webMethods Integration Server Built-In Services Reference Version 9.6

402

Odd Header
JDBC Folder

status

String A status indicating whether the service was able to

connect to the pool. A value of:
Active indicates that the service was able to connect to the

JDBC pool.

Inactive indicates that the service was not able to connect to

the JDBC pool or an invalid functional alias was specied.
If the aempt to connect to the JDBC pool failed with a
SQLException, the service might throw an exception. If the
service does not throw an exception, it will return a message
in the message variable.
message

String Conditional. Returned only if the service was not able

to connect to the JDBC pool. Contains one of the following
explanations:
Invalid functional alias.

An invalid or non-existent functional alias was specied with

the functionalAlias input parameter.
No pool is associated with this function or the pool
may have failed during initialization.

A valid functional alias was specied, but no pool is associated

with the functional alias, or the pool did not properly
initialize.

webMethods Integration Server Built-In Services Reference Version 9.6

403

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

404

Odd Header
JMS Folder

14 JMS Folder
Summary of Elements in This Folder ........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

406

405

Even Header
JMS Folder

You can use the services in the JMS folder to send and receive JMS messages.

Summary of Elements in This Folder

The following elements are available in this folder:
Element

Package and Description

pub.jms:acknowledge

WmPublic. Sends an acknowledgment for a

message to the JMS provider.

pub.jms:batchTriggerSpec

WmPublic. Specication for the signature of a JMS

trigger that processes a batch of messages at one
time.

pub.jms:createConsumer

WmPublic. Creates a message consumer to receive

messages from destinations on the JMS provider.

pub.jms:documentResolverSpec

WmPublic. Specication for the signature of a

document resolver service that determines whether
a JMS message has a status of New, Duplicate, or
In Doubt.

pub.jms:JMSMessage

WmPublic. Document type that represents

the structure and content of a JMS message
received by a JMS trigger, received by the service
pub.jms:receive, or as the output of pub.jms:send or
pub.jms:sendAndWait.

pub.jms:receive

WmPublic. Receives a message from a queue or

topic on the JMS provider.

pub.jms:reply

WmPublic. Sends a reply message to a requesting

client.

pub.jms:send

WmPublic. Sends a JMS message to the JMS

provider.

pub.jms:sendAndWait

WmPublic. Sends a request in the form of a JMS

message to the JMS provider and optionally, waits
for a reply.

webMethods Integration Server Built-In Services Reference Version 9.6

406

Odd Header
JMS Folder

Element

Package and Description

pub.jms:sendBatch

WmPublic. Sends multiple JMS messages to the

same destination on the JMS provider.

pub.jms:triggerSpec

WmPublic. Specication for the input signature of

a JMS trigger that processes one message at a time.

pub.jms:waitForReply

WmPublic. Retrieves the reply message for an

asynchronous request.

pub.jms.wmjms:receiveStream

WmPublic. Receives a large message stream from a

queue or topic on the webMethods Broker.

pub.jms.wmjms:sendStream

WmPublic. Sends a large message stream to the

webMethods Broker.

pub.jms:acknowledge
WmPublic. Sends an acknowledgment for a message to the JMS provider.
Input Parameters
message

Object A javax.jms.Message object that identies the message for which

you want Integration Server to send an acknowledgment to the JMS
provider.

Output Parameters
None.
Usage Notes
Use this service to acknowledge a message retrieved from the JMS provider if:
The message was received using the pub.jms:receive service, and
The message consumer used to retrieve the message has an acknowledgmentMode set
to CLIENT_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE. For more information about
creating a message consumer, see pub.jms:createConsumer.
A message is not considered to be successfully consumed until it is acknowledged.

webMethods Integration Server Built-In Services Reference Version 9.6

407

Even Header
JMS Folder

Note: Acknowledging a message automatically acknowledges the receipt of all messages

received in the same session. That is, all messages received by the same consumer will
be acknowledged when just one of the received messages is acknowledged.
See Also
pub.jms:createConsumer
pub.jms:receive

pub.jms:batchTriggerSpec
WmPublic. Specication for the signature of a JMS trigger that processes a batch of
messages at one time.
Input Parameters
JMSMessage

Document List A document list where each document references the

pub.jms:JMSMessage document type.

Output Parameters
None.
Usage Notes
Use this specication as the signature for JMS trigger services that will retrieve and
process a batch of messages.
If you want to use a JMS trigger to retrieve and process one message at a time, use
pub.jms:triggerSpec to declare the signature of the JMS trigger service.
See Also
pub.jms:triggerSpec
pub.jms:JMSMessage

pub.jms:createConsumer
WmPublic. Creates a message consumer to receive messages from destinations on the
JMS provider.
Input Parameters
connectionAliasName

String Name of the JMS connection alias that you want the
message consumer to receive messages.

webMethods Integration Server Built-In Services Reference Version 9.6

408

Odd Header
JMS Folder

The JMS connection alias indicates how Integration Server

connects to the JMS provider. A JMS connection alias can
specify that Integration Server use a JNDI provider to
look up administered objects (connection factories and
destinations) and then use the connection factory to create
a connection. Alternatively, a JMS connection alias can
specify that Integration Server uses the native webMethods
API to create the connection directly on the webMethods
Broker.
destinationName

String Name or lookup name of the Destination from

which you want the message consumer to receive
messages. Specify the lookup name of the Destination
object when the JMS connection alias uses JNDI to retrieve
administered objects. Specify the provider-specic name
of the Destination when the JMS connection alias uses
the native webMethods API to connect directly to the
webMethods Broker.

destinationType

String Optional. Type of destination from which the

message consumer receives messages. Specify one of the
following:
QUEUE to receive messages sent to a particular queue. This
is the default.
TOPIC to receive messages sent to a particular topic.

Note: You need to specify a destinationType only if you

specied a connectionAliasName that uses the native
webMethods API.
acknowledgmentMode

String Optional. Species the acknowledgment mode.

Specify one of the following:
AUTO_ACKNOWLEDGE to automatically acknowledge the
message when it is received by the message consumer.
The message consumer will acknowledge the message
before the message processing completes. The JMS
provider cannot redeliver the message if Integration
Server becomes unavailable before message processing
completes. This is the default.
CLIENT_ACKNOWLEDGE to acknowledge the receipt of a
message when the JMS client (Integration Server) invokes
pub.jms:acknowledge service.
DUPS_OK_ACKNOWLEDGE to automatically, lazily
acknowledge the receipt of messages, which reduces

webMethods Integration Server Built-In Services Reference Version 9.6

409

Even Header
JMS Folder

system overhead but may result in duplicate messages

being sent.
messageSelector

String Optional Species a lter used to receive a subset of

messages from the specied destination. A message selector
allows a client to lter the messages it wants to receive by
use of a SQL92 string expression in the message header.
That expression is applied to properties in the message
header (not to the message body content) containing the
value to be ltered.
If the SQL expression evaluates to true, the JMS provider
sends the message to the message consumer; if the SQL
expression evaluates to false, the JMS provider does not
send the message.

durableSubscriberName

String Optional. Name of the durable subscriber that you

want this service to create on the JMS provider. A durable
subscriber creates a durable subscription on the JMS
provider. If a durable subscriber of this name already exists
on the JMS provider, this service resumes the previously
established subscription.
Note: This parameter only applies when the destinationType
is set to TOPIC. If you select TOPIC, but do not specify a
durableSubscriberName , this service creates a nondurable
subscriber. If destinationType is set to QUEUE, this parameter is
ignored.

noLocal

java.lang.Boolean Optional. Flag indicating whether the

message consumer can receive locally published messages.
Integration Server considers a message to be local if the
message was:
Sent by the same Integration Server, and
Sent using the same JMS connection alias.
Specify one of the following values:
True to indicate that the consumer will not receive locally

published messages.

False to indicate that the consumer can receive locally

published messages. This is the default.

Note: This parameter only applies when the

destinationType is set to TOPIC.

webMethods Integration Server Built-In Services Reference Version 9.6

410

Odd Header
JMS Folder

Output Parameters
consumer

Object An on demand message consumer object used to

receive messages for the specied destination.

Usage Notes
A message consumer is a webMethods object that encapsulates the actual
javax.jms.MessageConsumer and javax.jms.Session.
Any message consumers created during the execution of a service will be closed
automatically when the top-level service completes. If the consumer closes without
acknowledging messages, messages are implicitly recovered back to the JMS provider.
The use of pub.jms:createConsumer in conjunction with pub.jms:receive is an alternative to
using JMS triggers. Use the pub.jms:createConsumer service to create a message consumer.
Use the pub.jms:receive to actively receive messages from a destination on the JMS
provider.
To create a durable subscriber, set the destinationType to TOPIC and specify a
durableSubscriberName. If you select TOPIC, but do not specify a durableSubscriberName ,
Integration Server creates a nondurable subscriber.
A durable subscription allows subscribers to receive all the messages published on a
topic, including those published while the subscriber is inactive.
If a durable subscription already exists for the specied durable subscriber on the JMS
provider, this service resumes the subscription.
A non-durable subscription allows subscribers to receive messages on their chosen
topic, only if the messages are published while the subscriber is active. A non-durable
subscription lasts the lifetime of its message consumer.
If the acknowledgment Mode eld is set to CLIENT_ACKNOWLEDGE, you must acknowledge
messages received by this consumer to the JMS provider using the pub.jms:acknowledge
service.
If the message consumer created by this service will be used to receive large message
streams from the webMethods Broker, make sure to specify an acknowledgmentMode
of AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE. If the acknowledgmentMode is
DUPS_OK_ACKNOWLEDGE, the message consumer cannot be used to receive large message
streams.
See Also
pub.jms:acknowledge
pub.jms:receive
pub.jms:reply
pub.jms:send
pub.jms:sendAndWait

webMethods Integration Server Built-In Services Reference Version 9.6

411

Even Header
JMS Folder

pub.jms:documentResolverSpec
WmPublic. Specication for the signature of a document resolver service that determines
whether a JMS message has a status of New, Duplicate, or In Doubt.
Input Parameters
uuid

String Universally unique identier for the message. If the sending

client assigned a value to the uuid eld in the message, Integration
Server uses the uuid value to identify the message. If the uuid eld
is empty, Integration Server uses the value of the JMSMessageID
eld in the message header as the UUID.

triggerName

String The name of the JMS trigger that received the message
whose status needs to be resolved.

JMSMessage

Document The message whose status needs to be resolved. This is

a document reference (IData) to the pub.jms:JMSMessage document
type, which denes the structure of a JMS message.

Output Parameters
status

String Indicates the status of the message. The value of this eld
determines whether the Integration Server processes or rejects the
message. The status eld will have one of the following values:
NEW indicates that the message is new and has not been processed

by the JMS trigger. Integration Server instructs the JMS trigger to

process the message.
DUPLICATE indicates that the message is a duplicate of one

already processed by the JMS trigger. Integration Server

acknowledges the message, but does not execute the trigger
service.
IN_DOUBT indicates that the status of the message is still in

doubt. The document resolver service could not conclusively

determine whether the JMS trigger already processed the
message. Integration Server acknowledges the message, but does
not execute the trigger service.
message

String Conditional. A user-specied string that indicates why the

message status is DUPLICATE or IN_DOUBT. Integration Server

webMethods Integration Server Built-In Services Reference Version 9.6

412

Odd Header
JMS Folder

writes this message to the journal log when the message has a
status of DUPLICATE or IN_DOUBT.
Usage Notes
The pub.jms:documentResolverSpec must be used as the signature for a document resolver
service used to determine the processing status of a JMS message received by a JMS
trigger. For information about building a document resolver service and enabling
exactly once processing for a JMS message, see Using webMethods Integration Server to
Build a Client for JMS.
Use pub.publish:documentResolverSpec as the signature for a document resolver service used
to determine the status of document received a webMethods messaging trigger.
See Also
pub.jms:JMSMessage
pub.publish:documentResolverSpec

pub.jms:JMSMessage
WmPublic. Document type that represents the structure and content of a JMS message
received by a JMS trigger, received by the service pub.jms:receive, or as the output of
pub.jms:send or pub.jms:sendAndWait.
Parameters
header

Document Optional. Document (IData object) containing the header of

the JMS message.
Key

Description

JMSCorrelationID

String Optional. A unique identier used

to link multiple messages together. Often,
a JMSCorrelationID is used to link a reply
message with its requesting message.

JMSDeliveryMode

java.lang.Integer Optional.Delivery mode

specied at the time the message was sent.
Delivery mode can be one of the following:
PERSISTENT to indicate that the JMS

provider places the message in a

persistent message store, allowing the
message to be recovered in the event of a
resource failure. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

413

Even Header
JMS Folder

NON-PERSISTENT to indicate that the JMS

provider does not place the message in

a persistent store. The message has no
guarantee of being delivered if the JMS
provider fails.

Note: When sending a message, this value

is obtained from the JMSMessage/header/
deliveryMode input parameter.
JMSDestination

Object Optional. Destination (queue or

topic) to which the message was sent.

JMSExpiration

java.lang.LongOptional. Time at which

this message expires. If the message
producer did not specify a time-to-live, the
JMSExpiration value is zero, indicating the
message does not expire.
Note: When sending a message, this value
is obtained from the JMSMessage/header/
timeToLive input parameter.

JMSMessageID

String. Optional. Unique identier assigned

to this message by the JMS provider.

JMSPriority

java.lang.Integer Optional. Denes the

message priority. The JMS standard denes
priority levels from 0 to 9, with 0 as the
lowest priority and 9 as the highest.
Note: When sending a message, this value is
obtained from the JMSMessage/header/priority
input parameter.

JMSRedelivered

java.lang.Boolean Optional. Flag indicating

the JMS provider delivered this message to
the JMS client previously. A value of:
True indicates that the message may have

been delivered in the past.

False indicates that the JMS provider has

not delivered this message previously.

JMSReplyTo

Object Optional. Destination to which a

reply to this message should be sent.

webMethods Integration Server Built-In Services Reference Version 9.6

414

Odd Header
JMS Folder

properties

body

JMSTimestamp

java.lang.Long Optional. Time at which the

message was given to the JMS provider.

JMSType

String Optional. Message type identier

specied by the client when sending the
message.

Document. Optional. A document containing optional elds added

to the message header. Integration Server may add the following
properties to JMS messages it sends or receives.
Key

Description

JMSXDeliveryCount

java.lang.Integer Optional. Species the

number of times the JMS provider
delivered the message. Most JMS providers
set this value.

JMS_WMClusterNodes

String Optional. Contains the name of the

Broker in a Broker cluster that will receive
the message or the name of the Broker or
Brokers in the Broker cluster that received
the JMS message.

activation

String Optional. A unique identier

assigned by the sender. An activation is
used to group together messages that will
be received by a JMS trigger with a join. A
JMS trigger can join together messages with
the same activation .

uuid

String Optional. A universally unique

identier for the message assigned by the
sender. Integration Server can use the uuid
for exactly-once processing or for request/
reply.

Document Optional A Document (IData) contenting the JMS message

body. Integration Server supports the following formats for the JMS
message body:
Key

Description

string

String Optional. Message body in the form

of a String.

webMethods Integration Server Built-In Services Reference Version 9.6

415

Even Header
JMS Folder

bytes

primitive type Optional Message body in the

form of a one-dimensional byte array.

object

Object. Optional. Message body in the form

of a Serializable Java object.

data

Document Optional. Message body in the

form of a document (IData object).
Note: This message format can only be used
when sending a JMS message from one
Integration Server to another. When the JMS
message is sent, the sending Integration
Server encodes the IData into a byte array.
When the receiving Integration Server
receives the message, it decodes the byte
array into IData.

message

Object Optional. Message body in the form

of an actual javax.jms.Message.
Note: When a JMS message is received using
the pub.jms:receive service this eld will always
be populated because javax.jms.Message is
required for acknowledging the message.
Note: When receiving a
javax.jms:MapMessage or
javax.jms:StreamMessage this eld will be
populated. The data can then be processed
using a Java service. A ow service cannot
process the message in its current state.

Output Parameters
None.
See Also
pub.jms:receive
pub.jms:send
pub.jms:sendAndWait

pub.jms:receive
WmPublic. Receives a message from a queue or topic on the JMS provider.

webMethods Integration Server Built-In Services Reference Version 9.6

416

Odd Header
JMS Folder

Input Parameters
consumer

Object A message consumer object that the session uses to

receive messages sent to the specied destination.

timeout

java.lang.Long Species the time to wait, in milliseconds, for a

message to be received from the JMS provider.
If you specify 0 (zero), the service will not wait.
The default is 0 (zero).

Output Parameters
JMSMessage

Document A document (IData) containing the JMS message received

by the consumer.
Key

Description

header

Document Conditional. A Document containing the

header elds for the received message.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link multiple
messages together. Often, a
JMSCorrelationID is used to link a
reply message with its requesting
message.

JMSDeliveryMode

java.lang.Integer
Conditional.Delivery mode
specied at the time the message
was sent.
PERSISTENT indicates the JMS

provider places the message in a

persistent message store, allowing
the message to be recovered in the
event of a resource failure.
NON-PERSISTENT indicates the

JMS provider does not place the

message in a persistent store. The

webMethods Integration Server Built-In Services Reference Version 9.6

417

Even Header
JMS Folder

message has no guarantee of being

delivered if the JMS provider fails.
JMSDestination

Object Conditional. Destination

(queue or topic) to which the
message was sent.

JMSExpiration

java.lang.LongConditional. Time at
which this message expires. If the
message producer did not specify
a time-to-live, the JMSExpiration
value is zero, indicating the
message does not expire.

JMSMessageID

String Conditional. Unique

identier assigned to this message
by the JMS provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message priority. The
JMS standard denes priority
levels from 0 to 9, with 0 as the
lowest priority and 9 as the highest.

JMSRedelivered

java.lang.Boolean Conditional.
Flag indicating the JMS provider
delivered this message to the JMS
client previously.
True indicates the message may

have been delivered in the past.

False indicates the JMS provider

has not delivered this message

previously.
JMSReplyTo

Object Conditional. Destination

to which a reply to this message
should be sent.

JMSTimestamp

java.lang.Long Conditional. Time at

which the message was given to the
JMS provider.

JMSType

String Conditional. Message type

identier specied by the client
when sending the message.

webMethods Integration Server Built-In Services Reference Version 9.6

418

Odd Header
JMS Folder

properties

Document Conditional. A Document containing optional

elds added to the message header. Integration Server
may add the following properties to JMS messages it
receives.
Key

Description

JMSXDelivery
Count

java.lang.Integer Conditional.
Species the number of times
the JMS provider delivered the
message. Most JMS providers set
this value.

JMS_WMCluster
Nodes

String Conditional. Name of the

Broker or Brokers in the Broker
cluster that received the JMS
message.
The Broker Server acting as the
JMS provider populates the
JMS_WMClusterNodes parameter
after it distributes the JMS message
to the Broker or Brokers in the
Broker cluster.
The JMS_WMClusterNodes value
will be null when:
The JMS provider is not the
Broker Server.
The JMS connection alias used to
send the JMS message does not
use a cluster connection factory
to obtain the connection to the
Broker Server.
The cluster connection factory
does not permit a policy to be
overridden.

activation

String Conditional. A unique

identier assigned by the sending
service. A JMS trigger uses the
activation value to determine if a
message satises a join.

uuid

String Conditional. A universally

unique identier for the message

webMethods Integration Server Built-In Services Reference Version 9.6

419

Even Header
JMS Folder

assigned by the sender. Integration

Server can use the uuid for exactlyonce processing or for request/
reply.
body

Document Conditional.A Document (IData) contenting

the JMS message body. Integration Server supports the
following formats for the JMS message body:
Key

Description

string

String Conditional. Message body

in the form of a String.

bytes

primitive type Conditional. Message

body in the form of a onedimensional byte array.

object

Object. Conditional. Message body

in the form of a Serializable Java
object.

data

Document Conditional. Message

body in the form of a document
(IData object).
Note: This message format can only
be used when sending a JMS message
from one Integration Server to
another. When the JMS message is
sent, the sending Integration Server
encodes the IData into a byte array.
When the receiving Integration
Server receives the message, it
decodes the byte array into IData.

message

Object Conditional. Message

body in the form of an actual
javax.jms.Message.
Note: When the JMS message is
received using the pub.jms:receive
service this eld will always be
populated because javax.jms.Message
is required for acknowledging the
message.

webMethods Integration Server Built-In Services Reference Version 9.6

420

Odd Header
JMS Folder

Note: When receiving a

javax.jms:MapMessage or
javax.jms:StreamMessage this eld
will be populated. The data can then
be processed using a Java service.
A ow service cannot process the
message in its current state.
Usage Notes
Use this service to receive a message from the JMS provider on demand. Receiving
a message on demand provides more control over when and how Integration Server
receives a message; however, it may not be as ecient or practical as using a JMS trigger
to listen for and then receive the message.
To listen for messages and receive them when they are available, create a JMS trigger
that listens to the destination. For more information about creating a JMS trigger, see the
webMethods Service Development Help.
If the timeout period elapses before a message is received, the value of JMSMessage is
null.
The message consumer that you use to receive the message determines the destination
from which this services receives messages and the JMS connection alias used to receive
the messages. You can create a message consumer object using the pub.jms:createConsumer
service.
After you receive a message, you need to invoke a service that processes the message.
If the acknowledgment mode of the consumer is set to CLIENT_ACKNOWLEDGE, use the
pub.jms:acknowledge service to acknowledge the message to the JMS provider.
See Also
pub.jms:acknowledge
pub.jms:createConsumer

pub.jms:reply
WmPublic. Sends a reply message to a requesting client.
Input Parameters
JMSReplyMessage

Document A document representing the JMS message reply.

Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

421

Even Header
JMS Folder

header

Document Optional. A document containing the

header of the replying JMS message.
Key

Description

deliveryMode

String Optional. Species the

message delivery mode for the
reply message. Specify one of the
following:
PERSISTENT

Default. Provide once-and-only-once

delivery for the message. The message
will not be lost if a JMS provider failure
occurs.
NON_PERSISTENT

Provide at-most-once delivery for

the message. The message has no
guarantee of being saved if a JMS
provider failure occurs.
priority

java.lang.Integer Optional. Species

the message priority. The JMS
standard denes priority levels from
0 to 9, with 0 as the lowest priority
and 9 as the highest.
The default is 4.

properties

timeToLive

java.lang.Long Optional. Length of

time, in milliseconds, that the JMS
provider system retains the reply
message. The default is 0, meaning
that the message does not expire.

JMSType

String Optional. Message type

identier for the message.

Document Optional. A Document containing optional

elds added to the message header.
Key

Description

activation

String Optional. A unique identier

that you want to assign to the
message. JMS triggers use the

webMethods Integration Server Built-In Services Reference Version 9.6

422

Odd Header
JMS Folder

activation value to determine if a

message satises a join.
uuid

body

String Optional. A universally

unique identier for the message.
Integration Server can use the uuid
for exactly-once processing or for
request/reply.

Document Optional. A Document containing the

JMS message body. Integration Server supports the
following formats for the JMS message body:
Key

Description

string

String Optional. Message body in the

form of a String.

bytes

primitive type Optional Message body

in the form of a one-dimensional
byte array.

object

Object. Optional. Message body in

the form of a Serializable Java object.

data

Document Optional. Message body

in the form of a document (IData
object).
Note: This message format can only
be used when sending a JMS message
from one Integration Server to another.
When the JMS message is sent, the
sending Integration Server encodes
the IData into a byte array. When the
receiving Integration Server receives
the message, it decodes the byte array
into IData.

message
consumer

Object Optional. Message body in the

form of a javax.jms.Message.

Object Optional. The message consumer object used to receive the

request message from the JMS provider. Integration Server uses
information from the consumer to create a message producer that
will send the reply message.

webMethods Integration Server Built-In Services Reference Version 9.6

423

Even Header
JMS Folder

You only need to specify a consumer when replying to a message

received using pub.jms:receive.
message

Object Optional. A javax.jms.Message object that contains the

request message.You can map the JMSMessage/body/message
eld in the request message to the pub.jms:replymessage input
parameter. The pub.jms:replyservice uses the request message to
determine the replyTo destination.
You only need to specify a message when replying to a message
received using pub.jms:receive.

Output Parameters
JMSReplyMessage

Document. A Document containing the reply message the JMS

provider sent to the client. After it sends a message, the JMS
provider populates some elds in the JMS reply message.
Key

Description

header

Document Conditional. A Document containing

the header elds for the reply message.
JMSCorrelation
ID

String Conditional. A unique

identier used to link the
reply message with the initial
request message.
The replying Integration
Server automatically sets this
value when it executes the
pub.jms:reply service.

JMSDelivery
Mode

java.lang.Integer Delivery mode

used to send the message.
PERSISTENT indicates that the
JMS provider provides onceand-only-once delivery for the
message. The message will not
be lost if a JMS provider failure
occurs.
NON_PERSISTENT indicates

that the JMS provider provides

at-most-once delivery for the
message. The message has no

webMethods Integration Server Built-In Services Reference Version 9.6

424

Odd Header
JMS Folder

guarantee of being saved if a

JMS provider failure occurs.
Note: When sending a reply
message, this value is obtained
from the JMSMessage/header/
deliveryMode input parameter.
JMSDestination

Object Conditional. Destination

(queue or topic) to which
the message was sent. The
JMSReplyTo value of the
request message determines
the destination of the reply
message.

JMSExpiration

java.lang.LongConditional. Time
at which this message expires.
If the message producer did
not specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does
not expire.
Note: When sending a message,
this value is obtained from
the JMSReplyMessage/header/
timeToLive input parameter.

JMSMessageID

String Conditional. Unique

identier assigned to this
message by the JMS provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message priority.
The JMS standard denes
priority levels from 0 to 9, with
0 as the lowest priority and 9
as the highest.
Note: When sending a reply
message, this value is obtained
from the JMSMessage/header/
priority input parameter.

JMSReplyTo

webMethods Integration Server Built-In Services Reference Version 9.6

Object Conditional. Species

the destination to which a

425

Even Header
JMS Folder

response to this message

should be sent.

properties

body

JMSTimestamp

java.lang.Long Time at which

the message was given to the
JMS provider.

JMSType

String Conditional. Message

type identier specied by
the client when sending the
message.

Document Conditional. A Document containing

optional elds added to the message header.
Integration Server may add the following
properties to JMS messages it receives.
Key

Description

activation

String Conditional. A unique

identier assigned by the
sending service. A JMS trigger
can join together messages
with the same activation .

uuid

String Conditional. A
universally unique identier
for the message assigned by
the sender. Integration Server
can use the uuid for exactlyonce processing or for request/
reply.

Document Conditional. A Document containing

the JMS message body. Integration Server
supports the following formats for the JMS
message body:
Key

Description

string

String Conditional. Message

body in the form of a String.

webMethods Integration Server Built-In Services Reference Version 9.6

426

Odd Header
JMS Folder

bytes

primitive type Conditional

Message body in the form of a
one-dimensional byte array.

object

Object. Conditional. Message

body in the form of a
Serializable Java object.

data

Document Conditional.
Message body in the form of a
document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is sent,
the sending Integration Server
encodes the IData into a byte
array. When the receiving
Integration Server receives the
message, it decodes the byte
array into IData.

message

Object Conditional. Message

body in the form of an actual
javax.jms.Message.

Usage Notes
The pub.jms:reply service creates a JMS message (javax.jms.Message) based on input
provided to the service or takes an existing JMS message and sends it to the JMS
provider as a reply to a requesting client.
The JMSReplyTo eld in the request message is set by the sending client and indicates
the destination to which the reply will be sent.
The replying Integration Server automatically sets this value when it executes the
pub.jms:reply service.
When executing the pub.jms:reply service, Integration Server automatically sets the value
of the JMSCorrelationID eld in the JMSReplyMessage . Integration Server uses the value
of either the uuid or JMSMessageID elds in the requesting JMS message to correlate the
request and the response. If you specify the uuid when sending the request, the replying
Integration Server will use the uuid as the JMSCorrelationID of the reply message. If
you do not specify a uuid , the replying Integration Server uses the JMSMessageID of the
request message as the JMSCorrelationID of the reply message.

webMethods Integration Server Built-In Services Reference Version 9.6

427

Even Header
JMS Folder

When replying to a message received using pub.jms:receive, you need to specify the input
parameters consumer and message .
If a transaction has not yet been started, the transaction manager starts a transaction
context for an implicit transaction when Integration Server executes a pub.jms:reply
service that uses a transacted JMS connection alias. A JMS connection alias is considered
to be transacted when it has a transaction type of XA TRANSACTION or LOCAL
TRANSACTION.
If you want more control over the actual javax.jms.Message that Integration
Server sends to the JMS provider, you can create a Java service that calls the
com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a
javax.jms.Message. See:
com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message, which
can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:reply
service.
When creating the javax.jms.Message with the
com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the
javax.jms.Message seer methods to set the values of the message headers and
properties directly. You can also set the value of message headers and properties using
the input parameters of the pub.jms:replyservice that you use to send the message. If
you set the message headers and properties both ways, the values provided to the
pub.jms:replyservice take precedence.
Software AG recommends that you use a pub.jms:reply service to create and send the
JMS message. This may provide beer performance on average. However, if you
want to send a StreamMessage or a MapMessage, you need to use the appropriate
com.wm.app.b2b.server.jms.producer.ProducerFacade API.
When using Universal Messaging or Nirvana 7 SP1 or later as the JMS provider, the
JMS client can use synchronous or asynchronous publishing. To ensure delivery of a
persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always
uses synchronous publishing to send a persistent JMS message to Universal Messaging
or Nirvana 7 SP1 or later.
Message priority is not supported when Universal Messaging or Nirvana is the JMS
provider. Any value specied in the priority eld will be ignored.
See Also
pub.jms:createConsumer
pub.jms:receive

webMethods Integration Server Built-In Services Reference Version 9.6

428

Odd Header
JMS Folder

pub.jms:send
WmPublic. Sends a JMS message to the JMS provider.
Input Parameters
connectionAlias
Name

String Name of the JMS connection alias that you want to use to
send the message.
The JMS connection alias indicates how Integration Server
connects to the JMS provider. A JMS connection alias can
specify that Integration Server use a JNDI provider to look up
administered objects (connection factories and destinations)
and then use the connection factory to create a connection.
Alternatively, a JMS connection alias can specify that Integration
Server uses the native webMethods API to create the connection
directly on the webMethods Broker.

destinationName

String Name or lookup name of the Destination to which you

want to send the message. Specify the lookup name of the
Destination object when the JMS connection alias uses JNDI to
retrieve administered objects. Specify the provider-specic name
of the Destination when the JMS connection alias uses the native
webMethods API to connect directly to the webMethods Broker.

destinationType

String Optional. Type of destination to which you want to send the

message. Specify one of the following:
QUEUE to send the message to a particular queue. This is the

default.

TOPIC to send the message to a topic.

Note: You need to specify destinationType only if you specied a

connectionAliasName that uses the native webMethods API.
JMSMessage

Document A document representing the JMS message you want to

send.
Key

Description

header

Document Optional. A document containing the

header of the JMS message.
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

429

Even Header
JMS Folder

deliveryMode

String Optional. Species the

message delivery mode for
the message. Specify one of
the following:
PERSISTENT

Default. Provide once-and-onlyonce delivery for the message.

The message will not be lost if a
JMS provider failure occurs.
NON_PERSISTENT

Provide at-most-once delivery

for the message. The message
has no guarantee of being saved
if a JMS provider failure occurs.
priority

java.lang.Integer Optional.
Species the message priority.
The JMS standard denes
priority levels from 0 to 9,
with 0 as the lowest priority
and 9 as the highest.
The default is 4.

properties

timeToLive

java.lang.Long Optional.
Length of time, in
milliseconds, that the JMS
provider retains the message.
The default is 0, meaning that
the message does not expire.

JMSType

String Optional. Message type

identier for the message.

Document Optional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties
to JMS messages it sends.
Key

Description

JMS_WMCluster
Nodes

String Optional. Name of the

Broker in a Broker cluster
that you want to receive
the message. The specied
Broker eectively overrides

webMethods Integration Server Built-In Services Reference Version 9.6

430

Odd Header
JMS Folder

the policy applied to the

cluster connection factory
used by the JMS connection
alias. If the applied policy
is multisend guaranteed or
multisend best eort, the
JMS_WMClusterNodes value
should contain multiple
Brokers.
Important: Software AG requires
that you specify the value
for JMS_WMClusterNodes
by mapping the contents of
the service output parameter
JMS_WMClusterNodes
produced by a previous
invocation of pub.jms:send or
pub.jms:sendAndWait.
Use this eld to override a
Broker cluster policy when all
of the following are true:
The Broker Server is the JMS
provider.
The JMS connection alias
used to send the message
(connectionAliasName ) uses
a connection from a cluster
connection factory.
The cluster connection
factory permits the applied
policy to be overridden.
Leave this eld blank if
the above conditions are
not met or if you want
the JMS message to be
distributed according to the
policy applied to the cluster
connection factory.
activation

webMethods Integration Server Built-In Services Reference Version 9.6

String Optional. A unique

identier used to group
together messages that will be
received by a JMS trigger with
a join. A JMS trigger can join
431

Even Header
JMS Folder

together messages with the

same activation .
uuid

body

String Optional. A universally

unique identier for the
message. Integration Server
can use the uuid for exactlyonce processing or for
request/reply.

Document Optional. A Document containing the

JMS message body. Integration Server supports
the following formats for the JMS message body:
Key

Description

string

String Optional. Message body

in the form of a String.

bytes

primitive type Optional

Message body in the form of a
one-dimensional byte array.

object

Object. Optional. Message

body in the form of a
Serializable Java object.

data

Document Optional. Message

body in the form of a
document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is sent,
the sending Integration Server
encodes the IData into a byte
array. When the receiving
Integration Server receives the
message, it decodes the byte
array into IData.

message

webMethods Integration Server Built-In Services Reference Version 9.6

Object Optional. Message

body in the form of an actual
javax.jms.Message.

432

Odd Header
JMS Folder

useCSQ

java.lang.Boolean Optional. Flag indicating whether Integration

Server places sent messages in the client side queue if the JMS
provider is not available at the time the messages are sent. Set to:
True to write messages to the client side queue if the JMS

provider is not available at the time this service executes. When

the JMS provider becomes available, Integration Server sends
messages from the client side queue to the JMS provider.
Note: If you want to use the client side queue with the
pub.jms:send service, the JMS connection alias specied for
connectionAliasName must be congured to have a client side
queue. A JMS connection alias has a client side queue if the
Maximum CSQ Size property for the alias is set to a value other
than 0 (zero).
False to throw an ISRuntimeException if the JMS provider is not

available at the time this service executes. This is the default.

Note: If the specied connectionAliasName uses a cluster

connection factory to which the multisend guaranteed policy is
applied, set useCSQ to False.
Output Parameters
JMSMessage

Document. A Document containing the message sent to the JMS

provider.
Key

Description

header

Document Conditional. A Document containing the

header elds for the sent message. The JMS provider
populates these elds after it has successfully
received the message from Integration Server.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link messages
together.

JMSDeliveryMode

java.lang.Integer Delivery mode

used to send the message.
PERSISTENT indicates that the
JMS provider provides onceand-only-once delivery for the

webMethods Integration Server Built-In Services Reference Version 9.6

433

Even Header
JMS Folder

message. The message will not

be lost if a JMS provider failure
occurs.
NON_PERSISTENT indicates
that the JMS provider provides
at-most-once delivery for the
message. The message has no
guarantee of being saved if a
JMS provider failure occurs.

Note: When sending a message,

this value is obtained from the
JMSMessage/header/deliveryMode
input parameter.
JMSDestination

Object Conditional. Destination

(queue or topic) to which the
message was sent.

JMSExpiration

java.lang.LongConditional. Time
at which this message expires.
If the message producer did
not specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does not
expire.
Note: When sending a message,
this value is obtained from the
JMSMessage/header/timeToLive
input parameter.

JMSMessageID

String Conditional. Unique

identier assigned to this
message by the JMS provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message priority.
The JMS standard denes
priority levels from 0 to 9, with
0 as the lowest priority and 9 as
the highest.
Note: When sending a message,
this value is obtained from the
JMSMessage/header/priority input
parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

434

Odd Header
JMS Folder

properties

JMSReplyTo

Object Conditional. Species the

destination to which a response
to this message should be sent.

JMSTimestamp

java.lang.Long Time at which the

message was given to the JMS
provider.

JMSType

String Conditional. Message

type identier specied by
the client when sending the
message.

Document Conditional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties to
JMS messages it sends.
Key

Description

JMS_WMCluster
Nodes

String Conditional. Name of the

Broker or Brokers in the Broker
cluster that received the JMS
message.
The Broker Server acting as
the JMS provider populates
the JMS_WMClusterNodes
parameter after it distributes the
JMS message to the Broker or
Brokers in the Broker cluster.
The JMS_WMClusterNodes
value will be null when:
The JMS provider is not the
Broker Server.
The JMS connection alias
used to send the JMS message
does not use a cluster
connection factory to obtain
the connection to the Broker
Server.
The cluster connection factory
does not permit a policy to be
overridden.

webMethods Integration Server Built-In Services Reference Version 9.6

435

Even Header
JMS Folder

body

activation

String Conditional. A unique

identier assigned by the
sender. A JMS trigger can join
together messages with the
same activation .

uuid

String Conditional. A universally

unique identier for the
message assigned by the sender.
Integration Server can use the
uuid for exactly-once processing
or for request/reply.

Document Conditional. A Document containing the

JMS message body. Integration Server supports the
following formats for the JMS message body:
Key

Description

string

String Conditional. Message

body in the form of a String.

bytes

primitive type Conditional

Message body in the form of a
one-dimensional byte array.

object

Object. Conditional. Message

body in the form of a
Serializable Java object.

data

Document Conditional. Message

body in the form of a document
(IData object).
Note: This message format can
only be used when sending a JMS
message from one Integration
Server to another. When the JMS
message is sent, the sending
Integration Server encodes the
IData into a byte array. When
the receiving Integration Server
receives the message, it decodes
the byte array into IData.

webMethods Integration Server Built-In Services Reference Version 9.6

436

Odd Header
JMS Folder

message

Object Conditional. Message

body in the form of an actual
javax.jms.Message.

Usage Notes
The pub.jms:send service creates a JMS message (javax.jms.Message) based on input
provided to the service or takes an existing JMS message and sends it to the JMS
provider.
If a transaction has not yet been started, the transaction manager starts a transaction
context for an implicit transaction when Integration Server executes a pub.jms:send
service that uses a transacted JMS connection alias. A JMS connection alias is considered
to be transacted when it has a transaction type of XA TRANSACTION or LOCAL
TRANSACTION.
You can add properties to a JMS message when building a ow service that invokes
this service. In Designer, use the Pipeline view to add a new variable to JMSMessage/
properties document.
If the JMS connection alias specied for connectionAliasName uses the native
webMethods API, you need to specify destinationName and destinationType to indicate
where the webMethods Broker should send the message.
Integration Server creates the output parameter JMSMessage because some of the header
elds in a JMS message are populated by the JMS provider after the message is sent. For
example, the header eld JMSMessageID is not in the JMS message sent by Integration
Server, but JMSMessageID is in the header after the JMS provider receives the message.
Each JMS connection alias can be congured to have its own client side queue. A JMS
connection alias has a client side queue if the Maximum CSQ Size property for the alias
is set to a value other than 0 (zero). If you want to use the client side queue with the
pub.jms:send service, the JMS connection alias specied for connectionAliasName must be
congured to have a client side queue. If the JMS connection alias is congured to use
a client side queue and useCSQ is set to true, Integration Server places messages in the
client side queue if the JMS provider is not available at the time the pub.jms:send service
executes. When the JMS provider becomes available, Integration Server sends messages
from the client side queue to the JMS provider.
The JMS provider populates the header elds in the JMSMessage output parameter after
it successfully receives the sent message from Integration Server. If the JMS provider is
not available at the time pub.jms:sendexecutes and useCSQ is set to true, the header elds
in the output JMSMessage will not be populated. Instead these elds will be blank or be
set to 0 (zero).
If the client side queue is not in use (useCSQ is set to false and/or the JMS connection
alias is not congured to use a client side queue, Integration Server throws an
ISRuntimeException if the JMS provider is not available when this service executes.
Make sure to code your service to handle this situation.

webMethods Integration Server Built-In Services Reference Version 9.6

437

Even Header
JMS Folder

A JMS connection alias can be congured so that Integration Server retries the
pub.jms:send service automatically when the service fails because of a transient error. For
more information about conguring a JMS connection alias for automatic retry, see the
webMethods Integration Server Administrators Guide.
When sending a message as part of a transaction the client side queue cannot be used.
That is, the useCSQ eld should be set to false. If useCSQ is set to true, Integration
Server throws a JMSSubsystemException when the pub.jms:send service executes. A
JMS message is sent as part of a transaction if the JMS connection alias specied in
connectionAliasName :
Uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
Connects to the webMethods Broker using a cluster connection factory to which the
multisend guaranteed policy is applied. Integration Server uses an XA transaction to
perform a two-phase commit when sending JMS messages.
If you want more control over the actual javax.jms.Message that Integration
Server sends to the JMS provider, you can create a Java service that calls the
com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a
javax.jms.Message. See:
com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message, which
can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send
service.
When creating the javax.jms.Message with the
com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the
javax.jms.Message seer methods to set the values of the message headers and
properties directly. You can also set the value of message headers and properties using
the input parameters of the pub.jms:sendservice that you use to send the message. If
you set the message headers and properties both ways, the values provided to the
pub.jms:sendservice take precedence.
Software AG recommends that you use a pub.jms:send service to create and send the
JMS message. This may provide beer performance on average. However, if you
want to send a StreamMessage or a MapMessage, you need to use the appropriate
com.wm.app.b2b.server.jms.producer.ProducerFacade API.
To send a StreamMessage, create a Java service that calls
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
javax.jms.Message object to the JMSMessage/body/message input parameter of the
pub.jms:send service.

webMethods Integration Server Built-In Services Reference Version 9.6

438

Odd Header
JMS Folder

To send a MapMessage, create a Java service that calls

com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
javax.jms.Message object to the JMSMessage/body/message input parameter of the
pub.jms:send service.
If you use the input parameter JMS_WMClusterNodes to override the policy applied to
the cluster connection factory, make sure to code the invoking service to handle any
exception that the Broker Server throws when policy requirements are not or cannot
be met. For more information about policy override scenarios that might result in an
exception from Broker Server, see Using webMethods Integration Server to Build a Client for
JMS.
When using Universal Messaging or Nirvana 7 SP1 or later as the JMS provider, the
JMS client can use synchronous or asynchronous publishing. To ensure delivery of a
persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always
uses synchronous publishing to send a persistent JMS message to Universal Messaging
or Nirvana 7 SP1 or later.
Message priority is not supported when Universal Messaging or Nirvana is the JMS
provider. Any value specied in the priority eld will be ignored.

pub.jms:sendAndWait
WmPublic. Sends a request in the form of a JMS message to the JMS provider and
optionally, waits for a reply.
Input Parameters
connectionAliasName

String Name of the JMS connection alias that you want to use
to send the message.
The JMS connection alias indicates how Integration Server
connects to the JMS provider. A JMS connection alias can
specify that Integration Server use a JNDI provider to
look up administered objects (connection factories and
destinations) and then use the connection factory to create a
connection. Alternatively, a JMS connection alias can specify
that Integration Server uses the native webMethods API to
create the connection directly on the webMethods Broker.

destinationName

String Name or lookup name of the Destination to which

you want to send the message. Specify the lookup name of
the Destination object when the JMS connection alias uses
JNDI to retrieve administered objects. Specify the providerspecic name of the Destination when the JMS connection

webMethods Integration Server Built-In Services Reference Version 9.6

439

Even Header
JMS Folder

alias uses the native webMethods API to connect directly to

the webMethods Broker.
destinationType

String Optional. Type of destination to which you want to send

the message. Specify one of the following:
QUEUE to send the message to a particular queue. This is the

default.

TOPIC to send the message to a topic.

Note: You need to specify a destinationType only if you

specied a connectionAliasName that uses the native
webMethods API.
destinationName
ReplyTo

String Optional. Name or lookup name of the Destination to

which you want the reply message sent. Specify the lookup
name of the Destination object when the JMS connection
alias uses JNDI to retrieve administered objects. Specify the
provider-specic name of the Destination when the JMS
connection alias uses the native webMethods API to connect
directly to the webMethods Broker.
If you do not specify a destination for reply messages,
Integration Server uses a temporaryQueue to receive the
reply. A temporaryQueue is a queue object created for the
duration of a particular connection. It can only be consumed
by the connection from which it was created.
If you want to use the client side queue with an asynchronous
request-reply, you must specify a queue that is not temporary
as the destinationNameReplyTo value.

destinationType
ReplyTo

String Optional. Type of destination to which you want the

reply to be sent. Specify one of the following:
QUEUE to send the reply message to a particular queue. This

is the default.

TOPIC to send the reply message to a specic topic.

timeout

java.lang.Long Optional. Time to wait (in milliseconds) for the

response to arrive. If no value is specied, the service does not
wait for a reply.
The timeout value only applies for a synchronous request/
reply. If async is set to true, Integration Server ignores the
timeout value.

webMethods Integration Server Built-In Services Reference Version 9.6

440

Odd Header
JMS Folder

JMSMessage

Document A document representing the JMS message you

want to send.
Key

Description

header

Document Optional. A document containing the

header of the JMS message.
Key

Description

deliveryMode

String Optional. Species the

message delivery mode for
the message. Specify one of
the following:
PERSISTENT

Default. Provide once-and-onlyonce delivery for the message.

The message will not be lost if a
JMS provider failure occurs.
NON_PERSISTENT

Provide at-most-once delivery

for the message. The message
has no guarantee of being saved
if a JMS provider failure occurs.
priority

java.lang.Integer Optional.
Species the message priority.
The JMS standard denes
priority levels from 0 to 9,
with 0 as the lowest priority
and 9 as the highest.
The default is 4.

timeToLive

java.lang.Long Optional. Length

of time, in milliseconds, that
the JMS provider retains the
message. The default is 0,
meaning that the message
does not expire.

JMSType

String Optional. Message type

identier for the message.
Integration Server expects the

webMethods Integration Server Built-In Services Reference Version 9.6

441

Even Header
JMS Folder

reply message to be of this

type.
properties

Document Optional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties
to JMS messages it sends.
Key

Description

JMS_WM
ClusterNodes

String Optional. Name of the

Broker in a Broker cluster
that you want to receive
the message. The specied
Broker eectively overrides
the policy applied to the
cluster connection factory
used by the JMS connection
alias. If the applied policy
is multisend guaranteed or
multisend best eort, the
JMS_WMClusterNodes value
should contain multiple
Brokers.
Important: Software AG requires
that you specify the value
for JMS_WMClusterNodes
by mapping the contents of
the service output parameter
JMS_WMClusterNodes
produced by a previous
invocation of pub.jms:send or
pub.jms:sendAndWait.
Use this eld to override a
Broker cluster policy when all
of the following are true:
The Broker Server is the JMS
provider.
The JMS connection alias
used to send the message
(connectionAliasName ) uses
a connection from a cluster
connection factory.

webMethods Integration Server Built-In Services Reference Version 9.6

442

Odd Header
JMS Folder

The cluster connection

factory permits the applied
policy to be overridden.
Leave this eld blank if
the above conditions are
not met or if you want
the JMS message to be
distributed according to the
policy applied to the cluster
connection factory.

body

activation

String Optional. A unique

identier used to group
together messages that will be
received by a JMS trigger with
a join. A JMS trigger can join
together messages with the
same activation .

uuid

String Optional. A universally

unique identier for the
message. Integration Server
can use the uuid for exactlyonce processing or for
request/reply.

Document Optional. A Document containing the

JMS message body. Integration Server supports
the following formats for the JMS message
body:
Key

Description

string

String Optional. Message body

in the form of a String.

bytes

primitive type Optional.

Message body in the form of a
one-dimensional byte array.

object

Object. Optional. Message

body in the form of a
Serializable Java object.

webMethods Integration Server Built-In Services Reference Version 9.6

443

Even Header
JMS Folder

data

Document Optional. Message

body in the form of a
document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is sent,
the sending Integration Server
encodes the IData into a byte
array. When the receiving
Integration Server receives the
message, it decodes the byte
array into IData.

message

async

Object Optional. Message

body in the form of an actual
javax.jms.Message.

java.lang.Boolean Optional. Flag specifying whether this is an

asynchronous or synchronous request/reply. Set to:
True to indicate that this is an asynchronous request/reply.

After sending the message, Integration Server executes the

next step in the ow service immediately. The Integration
Server does not wait for a reply before continuing service
execution.

Note: To retrieve the reply to an asynchronous send, invoke

the pub.jms:waitForReply service.
False to indicate that this is a synchronous request/reply.

After sending the message, the Integration Server waits for a

reply before executing the next step in the ow service. This
is the default.
useCSQ

java.lang.Boolean Optional. Flag indicating whether Integration

Server places sent messages in the client side queue if the JMS
provider is not available at the time the messages are sent. Set
to:
True to write messages to the client side queue if the JMS

provider is not available at the time this service executes.

When the JMS provider becomes available, Integration
Server sends messages from the client side queue to the JMS
provider.

webMethods Integration Server Built-In Services Reference Version 9.6

444

Odd Header
JMS Folder

Note: If you want to use the client side queue, the JMS
connection alias specied for connectionAliasName must be
congured to have a client side queue. A JMS connection
alias has a client side queue if the Maximum CSQ Size property
for the alias is set to a value other than 0 (zero).
False to throw an ISRuntimeException if the JMS provider

is not available at the time this service executes. This is the

default.

Note: Integration Server can write messages to the client side

queue only for messages sent as part of an asynchronous
request/reply. That is, if async is set to true (the default) and the
JMS provider is not available at the time this service executes,
Integration Server places the message in the client side queue.
Note: The client side queue cannot be used if the reply
destination is a temporary queue. Set useCSQ to False if
destinationNameReplyTo is not specied or is a temporary queue.
Note: If the specied connectionAliasName uses a cluster
connection factory to which the multisend guaranteed policy is
applied, set useCSQ to False.
Output Parameters
JMSMessage

Document. A Document containing the message sent to the JMS

provider.
Key

Description

header

Document Conditional. A Document containing

the header elds for the sent message. The
JMS provider populates these elds after it
has successfully received the message from
Integration Server.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link
messages together.

webMethods Integration Server Built-In Services Reference Version 9.6

445

Even Header
JMS Folder

JMSDeliveryMode

java.lang.Integer Delivery
mode used to send the
message.
PERSISTENT indicates that

the JMS provider provides

once-and-only-once delivery
for the message. The
message will not be lost if a
JMS provider failure occurs.
NON_PERSISTENT indicates

that the JMS provider

provides at-most-once
delivery for the message.
The message has no
guarantee of being saved
if a JMS provider failure
occurs.

Note: When sending

a message, this value
is obtained from the
JMSMessage/header/
deliveryMode input parameter.
JMSDestination

Object Conditional.
Destination (queue or topic)
to which the message was
sent.

JMSExpiration

java.lang.LongOptional.
Time at which this
message expires. If the
message producer did not
specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does
not expire.
Note: When sending
a message, this value
is obtained from the
JMSMessage/header/timeToLive
input parameter.

JMSMessageID

webMethods Integration Server Built-In Services Reference Version 9.6

String Conditional. Unique

identier assigned to

446

Odd Header
JMS Folder

this message by the JMS

provider.
JMSPriority

java.lang.Integer Optional.
Denes the message
priority. The JMS standard
denes priority levels from
0 to 9, with 0 as the lowest
priority and 9 as the highest.
Note: When sending
a message, this value
is obtained from the
JMSMessage/header/priority
input parameter.

properties

JMSReplyTo

Object Conditional. Species

the destination to which
a reply to this message
should be sent. The
destinationNameReplyTo
value determines the value
of JMSReplyTo .

JMSTimestamp

java.lang.Long Time at which

the message was given to
the JMS provider.

JMSType

String Conditional. Message

type identier specied by
the client when sending the
message.

Document Conditional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties
to JMS messages it sends.
Key

Description

JMS_WMCluster
Nodes

String Conditional. Name of

the Broker or Brokers in the
Broker cluster that received
the JMS message.
The Broker Server acting as
the JMS provider populates

webMethods Integration Server Built-In Services Reference Version 9.6

447

Even Header
JMS Folder

the JMS_WMClusterNodes
parameter after it distributes
the JMS message to the
Broker or Brokers in the
Broker cluster.
The JMS_WMClusterNodes
value will be null when:
The JMS provider is not
the Broker Server.
The JMS connection alias
used to send the JMS
message does not use a
cluster connection factory
to obtain the connection to
the Broker Server.
The cluster connection
factory does not permit a
policy to be overridden.

body

activation

String Conditional. A unique

identier assigned by the
sender. A JMS trigger can
join together messages with
the same activation .

uuid

String Conditional. A
universally unique identier
for the message assigned
by the sender. Integration
Server can use the uuid for
exactly-once processing or
for request/reply.

Document Conditional. A Document containing

the JMS message body. Integration Server
supports the following formats for the JMS
message body:
Key

Description

string

String Conditional. Message

body in the form of a String.

bytes

primitive type Conditional

Message body in the form

webMethods Integration Server Built-In Services Reference Version 9.6

448

Odd Header
JMS Folder

of a one-dimensional byte
array.
object

Object. Conditional. Message

body in the form of a
Serializable Java object.

data

Document Conditional.
Message body in the form of
a document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is
sent, the sending Integration
Server encodes the IData
into a byte array. When the
receiving Integration Server
receives the message, it
decodes the byte array into
IData.

message

Object Conditional. Message

body in the form of an
actual javax.jms.Message.

Document Conditional. Document containing the

JMS message received as a reply.

JMSReplyMessage

If this is a synchronous request/reply and

Integration Server does not receive a a reply
before the specied timeout value elapses, the
JMSReplyMessage is null.
If this is an asynchronous reply, the
JMSReplyMessage is null.
Key

Description

header

Document Conditional. A Document containing

the header elds for the reply message.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link the

webMethods Integration Server Built-In Services Reference Version 9.6

449

Even Header
JMS Folder

reply message with the

initial request message.
The replying Integration
Server automatically sets
this value when it executes
the pub.jms:reply service.
JMSDeliveryMode

java.lang.Integer Conditional.
Delivery mode used to send
the message.
PERSISTENT indicates that

the JMS provider provides

once-and-only-once delivery
for the message. The
message will not be lost if a
JMS provider failure occurs.
NON_PERSISTENT indicates

that the JMS provider

provides at-most-once
delivery for the message.
The message has no
guarantee of being saved
if a JMS provider failure
occurs.
JMSDestination

Object Conditional.
Destination (queue or topic)
to which the message was
sent.

JMSExpiration

java.lang.LongConditional.
Time at which this
message expires. If the
message producer did not
specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does
not expire.

JMSMessageID

String Conditional. Unique

identier assigned to
this message by the JMS
provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message

webMethods Integration Server Built-In Services Reference Version 9.6

450

Odd Header
JMS Folder

priority. The JMS standard

denes priority levels from
0 to 9, with 0 as the lowest
priority and 9 as the highest.
JMSRedelivered

java.lang.Boolean
Conditional. Flag indicating
the JMS provider delivered
this message to the JMS
client previously.
True indicates the message
may have been delivered in
the past.
False indicates the JMS

provider has not delivered

this message previously.

properties

JMSReplyTo

Object Conditional. Species

the destination to which a
response to this message
should be sent.

JMSTimestamp

java.lang.Long Conditional.
Time at which the message
was given to the JMS
provider.

JMSType

String Conditional. Message

type identier specied by
the client when sending the
message.

Document Conditional. A Document containing

optional elds added to the message header.
Integration Server adds the following proprieties
to JMS messages it receives.
Key

Description

JMSXDelivery
Count

java.lang.Integer Conditional.
Species the number of
times the JMS provider
delivered the message. Most
JMS providers set this value.

webMethods Integration Server Built-In Services Reference Version 9.6

451

Even Header
JMS Folder

JMS_WMCluster
Nodes

String Conditional. Name of

the Broker or Brokers in the
Broker cluster that received
the JMS message.
The Broker Server acting as
the JMS provider populates
the JMS_WMClusterNodes
parameter after it distributes
the JMS message to the
Broker or Brokers in the
Broker cluster.
The JMS_WMClusterNodes
value will be null when:
The JMS provider is not
the Broker Server.
The JMS connection alias
used to send the JMS
message does not use a
cluster connection factory
to obtain the connection to
the Broker Server.
The cluster connection
factory does not permit a
policy to be overridden.

body

activation

String Conditional. A unique

identier assigned by the
sender. A JMS trigger
uses the activation value
to determine whether a
message satises a join.

uuid

String Conditional. A
universally unique identier
for the message assigned
by the sender. Integration
Server can use the uuid for
exactly-once processing or
for request/reply.

Document Conditional. A Document containing

the JMS message body. Integration Server
supports the following formats for the JMS
message body:

webMethods Integration Server Built-In Services Reference Version 9.6

452

Odd Header
JMS Folder

Key

Description

string

String Conditional. Message

body in the form of a String.

bytes

primitive type Conditional

Message body in the form
of a one-dimensional byte
array.

object

Object. Conditional. Message

body in the form of a
Serializable Java object.

data

Document Conditional.
Message body in the form of
a document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is
sent, the sending Integration
Server encodes the IData
into a byte array. When the
receiving Integration Server
receives the message, it
decodes the byte array into
IData.

message

Object Conditional. Message

body in the form of an
actual javax.jms.Message.

Usage Notes
Thepub.jms:sendAndWait service creates a JMS message (javax.jms.Message) based on input
provided to the service or takes an existing JMS message, sends it to the JMS provider
and optionally, waits for a reply.
If a transaction has not been started, the transaction manager starts a transaction context
for an implicit transaction when Integration Server executes a pub.jms:sendAndWait service
that uses a transacted JMS connection alias. A JMS connection alias is considered
to be transacted when it has a transaction type of XA TRANSACTION or LOCAL
TRANSACTION.

webMethods Integration Server Built-In Services Reference Version 9.6

453

Even Header
JMS Folder

You can add properties to a JMS message when building a ow service that invokes
this service. In Designer, use the Pipeline view to add a new variable to JMSMessage/
properties document.
If the JMS connection alias specied for connectionAliasName uses the native
webMethods API, you need to specify destinationName and destinationType to indicate
where the webMethods Broker should send the message.
Integration Server creates the output parameter JMSMessage because some of the header
elds in a JMS message are populated by the JMS provider after the message is sent. For
example, the header eld JMSMessageID is not in the JMS message sent by Integration
Server, but JMSMessageID is in the header after the JMS provider receives the message.
You can use the pub.jms:sendAndWait service to initiate a request/reply. The sending client
sends a request for information to either a topic or queue. Clients that subscribe to the
destination compose and send a reply document that contains the information requested
by the sender.
A single request might receive many reply messages. Integration Server that sent the
request uses only the rst reply document it receives from the JMS provider. Integration
Server discards all other replies. First is arbitrarily dened. There is no guarantee
provided for the order in which the JMS provider processes incoming replies.
The pub.jms:sendAndWait service can be useful in situations where multiple sources contain
the response data. For example, suppose that an enterprise uses one application for
managing customer data, another for storing master customer records, and a mainframe
system for saving customer lists. Each of these applications could answer a request for
customer data. The requesting service will use the rst reply message it receives.
The pub.jms:sendAndWait service can issue a request/reply in a synchronous or
asynchronous manner.
In a synchronous request/reply, the service that sends the request stops executing
while it waits for a reply. When the service receives a reply message, the service
resumes execution. If the timeout elapses before the service receives a reply,
Integration Server ends the request, and the service returns a null message that
indicates that the request timed out. Integration Server then executes the next step in
the ow service.
In an asynchronous request/reply, the service that sends the request continues
executing the steps in the service after sending the message. To retrieve the reply,
the requesting ow service must invoke the pub.jms:waitForReply service. If the timeout
value specied in pub.jms:waitForReply elapses before the pub.jms:waitForReply service
receives a reply, the pub.jms:waitForReply service returns a null document indicating
that the request timed out.
When using pub.jms:sendAndWait to issue a request/reply, you must specify a queue as the
value of the destinationNameReplyTo parameter. In a request/reply scenario, it is possible
that the message consumer created to receive the reply might be created after the reply
message is sent. (In a synchronous request/reply, the pub.jms:sendAndWait service creates
the message consumer. In an asynchronous request/reply, the pub.jms:waitForReply service
or a custom solution, such as a JMS trigger, creates the message consumer.) If the reply

webMethods Integration Server Built-In Services Reference Version 9.6

454

Odd Header
JMS Folder

destination is a queue, a message consumer can receive messages published to the queue
regardless of whether the message consumer was active at the time the message was
published. If the destination is a topic, a message consumer can receive only messages
published when the message consumer was active. If the reply is sent to a topic before
the message consumer is created, the message consumer will not receive the reply.
Consequently, when creating a request/reply, the destinationNameReplyTo parameter
should specify the name or lookup name of a queue.
A service that contains multiple asynchronous send and wait invocations allows the
service to send all the requests before collecting the replies. This approach can be more
ecient than sending a request, waiting for a reply, and then sending the next request.
The replying Integration Server uses the value of uuid or JMSMessageID in the
requesting JMS message to correlate the request and the response. If you specify
the uuid when sending the request, the replying Integration Server will use the
uuid as the JMSCorrelationID of the reply message. If you do not specify a uuid , the
replying Integration Server uses the JMSMessageID set by the JMS provider as the
JMSCorrelationID of the reply message.
If you create a service that contains multiple asynchronous requests, make sure to
link the JMSMessage eld (uuid or JMSMessageID ) whose value will be used as the
reply message's JMSCorrelationID to another eld in the pipeline. Each asynchronous
request produces a JMSMessage document in the pipeline. If you do not link the uuid
or JMSMessageID eld from the JMSMessage document to another eld, the next
asynchronous request (that is, the next execution of the pub.jms:sendAndWait service), will
overwrite the previous JMSMessage document. When you invoke the pub.jms:waitForReply
service, the pipeline will contain only the input needed to retrieve the reply to the last
request. The pipeline will not contain the information needed to retrieve replies to
the previous requests. (That is, there will be nothing to map to the correlationID input
parameter of the pub.jms:waitForReply service.)
Each JMS connection alias can be congured to have its own client side queue. A JMS
connection alias has a client side queue if the Maximum CSQ Size property for the alias
is set to a value other than 0 (zero). If you want to use the client side queue with the
pub.jms:sendAndWait service, the JMS connection alias specied for connectionAliasName
must be congured to have a client side queue. If the JMS connection alias is congured
to use a client side queue and useCSQ is set to true, Integration Server places
messages in the client side queue if the JMS provider is not available at the time
the pub.jms:sendAndWait service executes. When the JMS provider becomes available,
Integration Server sends messages from the client side queue to the JMS provider.
If the client side queue is not used (useCSQ is set to false or the JMS connection
alias is not congured to have a client side queue), Integration Server throws an
ISRuntimeException if the JMS provider is not available when this service executes.
Make sure to code your service to handle this situation.
Integration Server can write messages to the client side queue only for messages sent as
part of an asynchronous request/reply. That is, if async is set to true (the default) and
the JMS provider is not available at the time this service executes, Integration Server
places the message in the client side queue. The client side queue cannot be used for a
synchronous request/reply.

webMethods Integration Server Built-In Services Reference Version 9.6

455

Even Header
JMS Folder

The client side queue cannot be used if the reply destination is a temporary
queue. Consequently, if useCSQ is set to true, values must be specied for the
destinationNameReplyTo and destinationTypeReplyTo input parameters. If these
parameters are not specied, Integration Serverthrows the following ServiceException
when it executes the pub.jms:sendAndWait service: [ISS.0134.9082] The client side queue
cannot be used with a send and wait request if the reply destination is a temporary
queue.
The JMS provider populates the header elds in the JMSMessage output parameter after
it successfully receives the sent message from Integration Server. If the JMS provider is
not available at the time the pub.jms:sendAndWait executes and useCSQ is set to true, the
header elds in the output JMSMessage will not be populated. Instead these elds will be
blank or be set to 0 (zero).
The pub.jms:waitForReply service cannot be used to retrieve response to requests that were
routed through the client side queue. To retrieve the response, create a JMS trigger that
subscribes to the reply to queue.
If the pub.jms:sendAndWait service executes and the message is sent directly to the
JMS provider (i.e., it is not sent to the client side queue), the JMSMessage\header
\JMSMessageID contains a unique identier assigned by the JMS provider. If the
JMSMessageID eld is null after the service executes, the JMS provider was not available
at the time the service executed.Integration Server wrote the message to the client side
queue.
When sending a message as part of a transaction client side queuing cannot be used.
That is, the useCSQ eld should be set to false. If useCSQ is set to true, Integration
Server throws a JMSSubsystemException when the pub.jms:sendAndWait service executes.
A JMS message is sent as part of a transaction if the JMS connection alias specied in
connectionAliasName :
Uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
Connects to the webMethods Broker using a cluster connection factory to which the
multisend guaranteed policy is applied. Integration Server uses an XA transaction to
perform a two-phase commit when sending JMS messages.
If you do not specify a destination for reply messages, Integration Server uses a
temporaryQueue to receive the reply. A temporaryQueue is a queue object created for
the duration of a particular connection. It can only be consumed by the connection from
which it was created.
If you want more control over the actual javax.jms.Message that Integration
Server sends to the JMS provider, you can create a Java service that calls the
com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a
javax.jms.Message. See:
com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)

webMethods Integration Server Built-In Services Reference Version 9.6

456

Odd Header
JMS Folder

com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message,
which can then be mapped to the JMSMessage/body/message input parameter of the
pub.jms:sendAndWait service.
When creating the javax.jms.Message with the
com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the
javax.jms.Message seer methods to set the values of the message headers and
properties directly. You can also set the value of message headers and properties using
the input parameters of the pub.jms:sendAndWaitservice that you use to send the message.
If you set the message headers and properties both ways, the values provided to the
pub.jms:sendAndWaitservice take precedence.
Software AG recommends that you use a pub.jms:sendAndWait service to create and send
the JMS message. This method may provide beer performance on average. However, if
you want to send a StreamMessage or a MapMessage, you need to use the appropriate
com.wm.app.b2b.server.jms.producer.ProducerFacade API.
To send a StreamMessage, create a Java service that calls
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
javax.jms.Message object to the JMSMessage/body/message input parameter of the
pub.jms:sendAndWait service.
To send a MapMessage, create a Java service that calls
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
javax.jms.Message object to the JMSMessage/body/message input parameter of the
pub.jms:sendAndWait service.
If you use the input parameter JMS_WMClusterNodes to override the policy applied to
the cluster connection factory, make sure to code the invoking service to handle any
exception that the Broker Server throws when policy requirements are not or cannot
be met. For more information about policy override scenarios that might result in an
exception from Broker Server, see Using webMethods Integration Server to Build a Client for
JMS.
When using Universal Messaging or Nirvana 7 SP1 or later as the JMS provider, the
JMS client can use synchronous or asynchronous publishing. To ensure delivery of a
persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always
uses synchronous publishing to send a persistent JMS message to Universal Messaging
or Nirvana 7 SP1 or later.
Message priority is not supported when Universal Messaging or Nirvana is the JMS
provider. Any value specied in the priority eld will be ignored.
See Also
pub.jms:reply
pub.jms:waitForReply
webMethods Integration Server Built-In Services Reference Version 9.6

457

Even Header
JMS Folder

pub.jms:sendBatch
WmPublic. Sends a group of JMS messages to the same destination on the webMethods
Broker.
Input Parameters
connectionAliasName
String Name of the JMS connection alias that you want to use to
send the messages.
The JMS connection alias indicates how Integration Server
connects to the webMethods Broker. A JMS connection alias
can specify that Integration Server use a JNDI provider to look
up administered objects (connection factories and destinations)
and then use the connection factory to create a connection.
Alternatively, a JMS connection alias can specify that Integration
Server uses the native webMethods API to create the connection
directly on the webMethods Broker.
Note: connectionAliasName must specify a JMS connection alias that
uses the webMethods Broker as the JMS provider.
destinationName

String Name or lookup name of the Destination to which you

want to send the messages. Specify the lookup name of the
Destination object when the JMS connection alias uses JNDI to
retrieve administered objects. Specify the provider-specic name
of the Destination when the JMS connection alias uses the native
webMethods API to connect directly to the webMethods Broker.
Note: When using the pub.jms:batchSend service, Integration Server
sends all messages to the same destination.

destinationType

String Optional. Type of destination to which you want to send the

message. Specify one of the following:
QUEUE to send the message to a particular queue. This is the

default.

TOPIC to send the message to a topic.

Note: You need to specify destinationType only if you specied a

connectionAliasName that uses the native webMethods API.
deliveryMode

String Optional. Species the message delivery mode for the

messages. Specify one of the following:

webMethods Integration Server Built-In Services Reference Version 9.6

458

Odd Header
JMS Folder

PERSISTENT Default. Provide once-and-only-once delivery for

the messages. The messages will not be lost if a webMethods

Broker failure occurs.
NON_PERSISTENT Provide at-most-once delivery for the

messages. The messages have no guarantee of being saved if a

webMethods Broker failure occurs.
Note: The specied delivery mode applies to all of the messages sent
by the service.
priority

java.lang.Integer Optional. Species the message priority for all of

the messages. The JMS standard denes priority levels from 0 to 9,
with 0 as the lowest priority and 9 as the highest.
The default is 4.
Note: The specied priority applies to all of the messages sent by the
service.

timeToLive

java.lang.Long Optional. Length of time, in milliseconds, that

the webMethods Broker retains each message. The default is 0,
meaning that the messages do not expire.
Note: The specied time to live applies to all of the messages sent by
the service.

JMSMessages

Document List A document list representing the JMS messages

to send to the destination. Specify the following for each JMS
message that you want to send:
Key

Description

header

Document Optional. A document containing the

header of the JMS message.

properties

Key

Description

JMSType

String Optional. Message type

identier for the message.

Document Optional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties
to JMS messages it sends.

webMethods Integration Server Built-In Services Reference Version 9.6

459

Even Header
JMS Folder

body

Key

Description

activation

String Optional. A unique

identier used to group
together messages that will be
received by a JMS trigger with
a join. A JMS trigger can join
together messages with the
same activation .

uuid

String Optional. A universally

unique identier for the
message. Integration Server
can use the uuid for exactlyonce processing or for
request/reply.

Document Optional. A Document containing the

JMS message body. Integration Server supports
the following formats for the JMS message body:
Key

Description

string

String Optional. Message body

in the form of a String.

bytes

primitive type Optional

Message body in the form of a
one-dimensional byte array.

object

Object. Optional. Message

body in the form of a
Serializable Java object.

data

Document Optional. Message

body in the form of a
document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is sent,
the sending Integration Server
encodes the IData into a byte
array. When the receiving

webMethods Integration Server Built-In Services Reference Version 9.6

460

Odd Header
JMS Folder

Integration Server receives the

message, it decodes the byte
array into IData.
message

Object Optional. Message

body in the form of an actual
javax.jms.Message.

Note: When you send a batch of messages, you can

specify a dierent format for each JMS message
body.
useCSQ

java.lang.Boolean Optional. Flag indicating whether Integration

Server places sent messages in the client side queue if the
webMethods Broker is not available at the time the messages are
sent. Set to:
True to write messages to the client side queue if the

webMethods Broker is not available at the time this service

executes. When the webMethods Broker becomes available,
Integration Server sends messages from the client side queue to
the webMethods Broker.
Note: If you want to use the client side queue, the JMS connection
alias specied for connectionAliasName must be congured to
have a client side queue. A JMS connection alias has a client side
queue if the Maximum CSQ Size property for the alias is set to a
value other than 0 (zero).
False to throw an ISRuntimeException if the webMethods

Broker is not available at the time this service executes. This is the
default.
Output Parameters
JMSMessages

Document List A Document list containing the messages sent to

the webMethods Broker. Each document contains the following
information:
Key

Description

header

Document Conditional. A Document containing the

header elds for the sent message. The webMethods
Broker populates these elds after it has successfully
received the message from Integration Server.

webMethods Integration Server Built-In Services Reference Version 9.6

461

Even Header
JMS Folder

Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link messages
together.

JMSDeliveryMode

java.lang.Integer Delivery mode

used to send the message.
PERSISTENT indicates that the

JMS provider provides onceand-only-once delivery for the

message. The message will not
be lost if a JMS provider failure
occurs.
NON_PERSISTENT indicates

that the JMS provider provides

at-most-once delivery for the
message. The message has no
guarantee of being saved if a
JMS provider failure occurs.
Note: When sending a message,
this value is obtained from the
JMSMessage/header/deliveryMode
input parameter.
JMSDestination

Object Conditional. Destination

(queue or topic) to which the
message was sent.

JMSExpiration

java.lang.LongConditional. Time
at which this message expires.
If the message producer did
not specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does not
expire.
Note: When sending a message,
this value is obtained from the
JMSMessage/header/timeToLive
input parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

462

Odd Header
JMS Folder

JMSMessageID

String Conditional. Unique

identier assigned to this
message by the JMS provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message priority.
The JMS standard denes
priority levels from 0 to 9, with
0 as the lowest priority and 9 as
the highest.
Note: When sending a message,
this value is obtained from the
JMSMessage/header/priority input
parameter.

properties

JMSReplyTo

Object Conditional. Species the

destination to which a response
to this message should be sent.

JMSTimestamp

java.lang.Long Time at which the

message was given to the JMS
provider.

JMSType

String Conditional. Message type

identier specied by the client
when sending the message.

Document Conditional. A Document containing

optional elds added to the message header.
Integration Server adds the following properties to
JMS messages it sends.
Key

Description

activation

String Conditional. A unique

identier assigned by the
sender. A JMS trigger can join
together messages with the same
activation .

uuid

String Conditional. A universally

unique identier for the
message assigned by the sender.
Integration Server can use the

webMethods Integration Server Built-In Services Reference Version 9.6

463

Even Header
JMS Folder

uuid for exactly-once processing

or for request/reply.
body

Document Conditional. A Document containing the

JMS message body. Integration Server supports the
following formats for the JMS message body:
Key

Description

string

String Conditional. Message

body in the form of a String.

bytes

primitive type Conditional

Message body in the form of a
one-dimensional byte array.

object

Object. Conditional. Message

body in the form of a Serializable
Java object.

data

Document Conditional. Message

body in the form of a document
(IData object).
Note: This message format can
only be used when sending a JMS
message from one Integration
Server to another. When the JMS
message is sent, the sending
Integration Server encodes the
IData into a byte array. When
the receiving Integration Server
receives the message, it decodes
the byte array into IData.

message

Object Conditional. Message

body in the form of an actual
javax.jms.Message.

Usage Notes
The pub.jms:sendBatch service can be used only with the webMethods Broker. If you set
the connectionAliasName parameter to a JMS connection alias that uses a dierent JMS
provider, the pub.jms:sendBatch service ends with an exception.

webMethods Integration Server Built-In Services Reference Version 9.6

464

Odd Header
JMS Folder

The pub.jms:sendBatch service creates multiple JMS messages (javax.jms.Message) based

on input provided to the service or takes existing JMS messages and sends them to the
webMethods Broker.
Sending a batch of messages using the pub.jms:sendBatch service is an all or nothing
operation. If Integration Server or the webMethods Broker determine that one of the
messages is not valid during a pre-processing check, none of the messages will be sent.
Make sure to code your service to handle this possibility.
The pub.jms:sendBatch service can be used to send messages in accordance with a
supported cluster policy. A cluster policy, which is applied to a connection factory
used by a JMS connection alias, determines the Broker to which the JMS messages are
sent. The pub.jms:sendBatch service works with the round robin, sticky, random, and
weighted round robin cluster policies. The pub.jms:sendBatch service does not work with
the multisend guaranteed or multisend best eort cluster policies.
The pub.jms:sendBatch service cannot be used to override the cluster policy assigned to the
connection factory used by the JMS connection alias.
When Integration Server executes a pub.jms:sendBatch service that uses a transacted JMS
connection alias, Integration Server sends the messages as part of a transaction. If a
transaction has not yet been started, the transaction manager starts a transaction context
for an implicit transaction A JMS connection alias is considered to be transacted when it
has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.
You can add properties to a JMS message when building a ow service that invokes this
service. To add a new property, use the Pipeline to add a new variable to JMSMessages/
properties document.
If the JMS connection alias specied for connectionAliasName uses the native
webMethods API, you need to specify destinationName and destinationType to indicate
where the webMethods Broker should send the message.
Integration Server creates the output parameter JMSMessages because some of the header
elds in a JMS message are populated by the JMS provider after the message is sent. For
example, the header eld JMSMessageID is not in the JMS message sent by Integration
Server, but JMSMessageID is in the header after the JMS provider receives the message.
Each JMS connection alias can be congured to have its own client side queue. A JMS
connection alias has a client side queue if the Maximum CSQ Size property for the alias
is set to a value other than 0 (zero). If you want to use the client side queue with the
pub.jms:sendBatch service, the JMS connection alias specied for connectionAliasName must
be congured to have a client side queue. If the JMS connection alias is congured to
use a client side queue and useCSQ is set to true, Integration Server places messages in
the client side queue if the JMS provider is not available at the time the pub.jms:sendBatch
service executes. When the JMS provider becomes available, Integration Server sends
messages from the client side queue to the JMS provider.
If the client side queue is not used (useCSQ is set to false or the JMS connection
alias is not congured to have a client side queue), Integration Server throws an
ISRuntimeException if the JMS provider is not available when this service executes.
Make sure to code your service to handle this situation.

webMethods Integration Server Built-In Services Reference Version 9.6

465

Even Header
JMS Folder

When sending a message as part of a transaction, the client side queue cannot be
used. The useCSQ eld should be set to false. If useCSQ is set to true, Integration
Server throws a JMSSubsystemException when the pub.jms:send service executes.
A JMS message is sent as part of a transaction if the JMS connection alias specied
in connectionAliasName uses a transaction type of LOCAL_TRANSACTION or
XA_TRANSACTION.
The JMS provider populates the header elds in the JMSMessages output parameter after
it successfully receives the sent message from Integration Server. If the JMS provider is
not available at the time pub.jms:sendBatchexecutes and useCSQ is set to true, the header
elds in the output JMSMessages will not be populated. Instead these elds will be blank
or be set to 0 (zero).
If you want more control over the actual javax.jms.Message that Integration
Server sends to the JMS provider, you can create a Java service that calls the
com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a
javax.jms.Message. See:
com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message, which
can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send
service.
When creating the javax.jms.Message with the
com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the
javax.jms.Message seer methods to set the values of the message headers and
properties directly. You can also set the value of message headers and properties using
the input parameters of the pub.jms:sendservice that you use to send the message. If
you set the message headers and properties both ways, the values provided to the
pub.jms:sendservice take precedence.
Software AG recommends that you use a pub.jms:sendBatch service to create and send
the JMS message. This may provide beer performance on average. However, if you
want to send a StreamMessage or a MapMessage, you need to use the appropriate
com.wm.app.b2b.server.jms.producer.ProducerFacade API.
To send a StreamMessage, create a Java service that calls
com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
javax.jms.Message object to the JMSMessage/body/message input parameter of the
pub.jms:send service.
To send a MapMessage, create a Java service that calls
com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java
service calling this API must return an Object of type javax.jms.Message. Map the
webMethods Integration Server Built-In Services Reference Version 9.6

466

Odd Header
JMS Folder

javax.jms.Message object to the JMSMessage/body/message input parameter of the

pub.jms:send service.
When using Universal Messaging or Nirvana 7 SP1 or later as the JMS provider, the
JMS client can use synchronous or asynchronous publishing. To ensure delivery of a
persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always
uses synchronous publishing to send a persistent JMS message to Universal Messaging
or Nirvana 7 SP1 or later.
Message priority is not supported when Universal Messaging or Nirvana is the JMS
provider. Any value specied in the priority eld will be ignored.

pub.jms:triggerSpec
WmPublic. Specication for the input signature of a JMS trigger that processes one
message at a time.
Input Parameters
JMSMessage

Document A document reference (IData) to the

pub.jms:JMSMessage document type, which denes the structure
of a JMS message.

Output Parameters
None.
Usage Notes
If you want to use a JMS trigger to retrieve and process multiple messages in one batch,
use pub.jms:batchTriggerSpec to declare the inputs and outputs of the JMS trigger service.
See Also
pub.jms:batchTriggerSpec
pub.jms:JMSMessage

pub.jms:waitForReply
WmPublic. Retrieves the reply message for an asynchronous request.
Input Parameters
correlationID

String Unique identier used to associate the reply message

with the initial request.

webMethods Integration Server Built-In Services Reference Version 9.6

467

Even Header
JMS Folder

timeout

java.lang.Long Optional. Time to wait (in milliseconds) for the

reply to arrive. If no value is specied, the service does not
wait for a reply.

Output Parameters
JMSReplyMessage

Document Conditional. Document containing the JMS message

received as a reply.
If this is an asynchronous request/reply and Integration Server
does not receive a a reply before the specied timeout value
elapses, the JMSReplyMessage is null.
Key

Description

header

Document Conditional. A Document containing the

header elds for the reply message.
Key

Description

JMSCorrelationID

String Conditional. A unique

identier used to link the
reply message with the
initial request message.

JMSDeliveryMode

java.lang.Integer Conditional.
Delivery mode used to send
the message.
PERSISTENT indicates that
the JMS provider provides
once-and-only-once delivery
for the message. The
message will not be lost if a
JMS provider failure occurs.
NON_PERSISTENT indicates

that the JMS provider

provides at-most-once
delivery for the message.
The message has no
guarantee of being saved if a
JMS provider failure occurs.
JMSDestination

webMethods Integration Server Built-In Services Reference Version 9.6

Object Conditional.
Destination (queue or topic)

468

Odd Header
JMS Folder

to which the message was

sent.
JMSExpiration

java.lang.LongConditional.
Time at which this
message expires. If the
message producer did not
specify a time-to-live, the
JMSExpiration value is zero,
indicating the message does
not expire.

JMSMessageID

String Conditional. Unique

identier assigned to
this message by the JMS
provider.

JMSPriority

java.lang.Integer Conditional.
Denes the message
priority. The JMS standard
denes priority levels from
0 to 9, with 0 as the lowest
priority and 9 as the highest.

JMSRedelivered

java.lang.Boolean Conditional.
Flag indicating the JMS
provider delivered this
message to the JMS client
previously.
True indicates the message

may have been delivered in

the past.
False indicates the JMS

provider has not delivered

this message previously.
JMSReplyTo

Object Conditional. Species

the destination to which a
response to this message
should be sent.

JMSTimestamp

java.lang.Long Conditional.
Time at which the message
was given to the JMS
provider.

webMethods Integration Server Built-In Services Reference Version 9.6

469

Even Header
JMS Folder

JMSType

properties

String Conditional. Message

type identier specied by
the client when sending the
message.

Document Conditional. A document containing

optional elds added to the message header.
Integration Server may add the following
properties to JMS messages it sends or receives.
Key

Description

JMSXDeliveryCount

java.lang.Integer Conditional.
Species the number of
times the JMS provider
delivered the message to the
requesting client. Most JMS
providers set this value.

JMS_WMCluster
Nodes

String Conditional. Name of

the Broker or Brokers in the
Broker cluster that received
the JMS message.
The Broker Server acting as
the JMS provider populates
the JMS_WMClusterNodes
parameter after it distributes
the JMS message to the
Broker or Brokers in the
Broker cluster.
The JMS_WMClusterNodes
value will be null when:
The JMS provider is not the
Broker Server.
The JMS connection alias
used to send the JMS
message does not use a
cluster connection factory
to obtain the connection to
the Broker Server.
The cluster connection
factory does not permit a
policy to be overridden.

webMethods Integration Server Built-In Services Reference Version 9.6

470

Odd Header
JMS Folder

body

activation

String Conditional. A unique

identier assigned by the
sending service. A JMS
trigger uses the activation
to determine whether a
message is part of a join.

uuid

String Conditional. A
universally unique identier
for the message assigned
by the sender. Integration
Server can use the uuid for
exactly-once processing or
for request/reply.

Document Conditional. A Document containing the

JMS message body. Integration Server supports
the following formats for the JMS message body:
Key

Description

string

String Conditional. Message

body in the form of a String.

bytes

primitive type Conditional

Message body in the form
of a one-dimensional byte
array.

object

Object. Conditional. Message

body in the form of a
Serializable Java object.

data

Document Optional. Message

body in the form of a
document (IData object).
Note: This message format can
only be used when sending
a JMS message from one
Integration Server to another.
When the JMS message is sent,
the sending Integration Server
encodes the IData into a byte
array. When the receiving
Integration Server receives the

webMethods Integration Server Built-In Services Reference Version 9.6

471

Even Header
JMS Folder

message, it decodes the byte

array into IData.
message

Object Optional. Message

body in the form of an
actual javax.jms.Message.

Usage Notes
Integration Server uses the value of the uuid or JMSMessageID elds in the requesting
JMS message to correlate the response to the request. If you specify the uuid
when sending the request, the replying Integration Server will use the uuid as the
JMSCorrelationID of the reply message (JMSReplyMessage ). If you do not specify a uuid ,
the replying Integration Server uses the JMSMessageID set by the JMS provider as the
JMSCorrelationID of the reply message (JMSReplyMessage ).
If you set the uuid in the JMS message request, you can link the value of the uuid eld
from the JMSMessage produced by the pub.jms:sendAndWait service to the correlationID
input eld of the pub.jms:waitForReply service. If you did not specify a uuid , you can link
the JMSMessageID eld from the JMSMessage produced by the pub.jms:sendAndWait to the
correlationID input eld.
The timeout value of the sending service species how long Integration Server will
keep the request open while waiting for a reply. If a reply is not available at the time
Integration Server executes the pub.jms:waitForReply service, Integration Server continues
to wait for the document until the time specied in the timeout parameter elapses. If
Integration Server does not receive a reply by the time the timeout interval elapses,
the pub.jms:waitForReply service returns a null document. This indicates that the timeout
interval expired.
The pub.jms:waitForReply service cannot be used to retrieve response to requests that were
routed through the client side queue. To retrieve the response, create a JMS trigger that
subscribes to the reply to queue
If the pub.jms:sendAndWait service executes and the message is sent directly to the
JMS provider (i.e., it is not sent to the client side queue), the JMSMessage\header
\JMSMessageID contains a unique identier assigned by the JMS provider. If the
JMSMessageID eld is null after the service executes, the JMS provider was not available
at the time the service executed. Integration Server wrote the message to the client side
queue.
See Also
pub.jms:sendAndWait

pub.jms.wmjms:receiveStream
WmPublic. Receives a large message stream from a queue or topic on the webMethods
Broker.

webMethods Integration Server Built-In Services Reference Version 9.6

472

Odd Header
JMS Folder

Input Parameters
consumer

Object A message consumer object that the service uses

to receive the large message stream. Create the message
consumer object using the pub.jms:createConsumer service.

timeout

java.lang.Long Optional. Time to wait (in milliseconds) for the

rst part of the message stream. If you do not specify a timeout
value, the consumer does not wait.

Output Parameters
stream

Object A com.webmethods.jms.impl.WmJMSInputStream
received by the consumer.
If the timeout value elapses before a message is received,
stream will be null.

Usage Notes
When using webMethods Broker as the JMS provider, the webMethods message
streaming feature allows you to stream large amounts of data or a large le from a
message producer to a message consumer.
Important: You can only send and receive large messages from Integration Server
when working with the webMethods Broker. For more information about how the
webMethods message streaming feature works on the webMethods Broker, see the
webMethods Broker Messaging Programmers Guide.
Large message streams cannot be sent or received as part of a transaction.
If the JMS connection alias used by the consumer has a transaction type of
LOCAL_TRANSACTION or XA_TRANSACTION, Integration Server throws an
exception, specically com.wm.app.b2b.server.jms.JMSSubsystemException, when it
executes the pub.jms.wmjms:receiveStream service.
The consumer that you use to receive the message determines the destination from
which this services receives messages and the JMS connection alias used to receive the
messages. You can create a message consumer object using the pub.jms:createConsumer
service.
The timeout value species how long the message consumer waits for the initial part of
the message stream. If a message is not returned when the time out period elapses, the
pub.jms.wmjms:receiveStream returns a null value.
The read timeout is the maximum length of time the consumer waits between receiving
subsequent pieces of the message stream. After the read timeout elapses, the consumer
calls InputStream.read() to read the next byte of the stream. If the next byte of the stream

webMethods Integration Server Built-In Services Reference Version 9.6

473

Even Header
JMS Folder

is not available, Integration Server throws a WmReadTimeoutException. The read

timeout only applies after the consumer receives the rst part of the message stream.
The watt.server.jms.wmjms.lms.readTimeout property determines the read timeout
value. The default is 30000 milliseconds.
Make sure to code your service to handle a WmReadTimeoutException. When an
WmReadTimeoutException occurs, it suggests that Integration Server did not receive
the entire message stream. When this occurs, you need to close the stream, which will
acknowledge it to the webMethods Broker. You can close the stream from a Java service
by calling Input.Stream.close. You can also close the stream using the pub.io:close service.
If the connection between the Integration Server and webMethods Broker fails
during execution of the pub.jms.wmjms:receiveStream service, Integration Server throws
a WmConnectionException. When this occurs, Integration Server rolls the message
back to the webMethods Broker automatically. The message can be received when the
connection to the webMethods Broker is re-established.
You can code your service to implement recoverability logic. This means that the next
time the message stream is received, the service re-processes the message stream from
the point at which processing stopped. To resume processing from the correct point,
the service needs to keep track of the message ID and byte position. For more details,
com.webmethods.jms.impl.WmJMSInputStream.
After the pub.jms.wmjms:receiveStream receives and processes the last part of the message
stream, you need to close the stream. InputStream.read() returns "-1" when the end
of the stream is reached. You can close the stream from a Java service by calling
Input.Stream.close. You can also close the stream using the pub.io:close service. Closing
the stream explicitly acknowledges the message to the provider.
The consumer used to receive large message streams from the webMethods Broker
can specify an acknowledgmentMode of AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE.
webMethods Broker does not permit the use of the acknowledgmentMode is
DUPS_OK_ACKNOWLEDGE for the webMethods message streaming feature.
You might want to use the scheduler capabilities within Integration Server to schedule
a service that receives and then process large messages from webMethods Broker
For more information about scheduling services, see webMethods Integration Server
Administrators Guide.
See Also
pub.io:close
pub.jms:createConsumer
pub.jms.wmjms:sendStream
pub.jms.wmjms:sendStream

pub.jms.wmjms:sendStream
WmPublic. Sends a large message stream to the webMethods Broker.

webMethods Integration Server Built-In Services Reference Version 9.6

474

Odd Header
JMS Folder

Input Parameters
connectionAliasName

String Name of the JMS connection alias that you want to use
to send the message.

destinationName

String Name or lookup name of the Destination to which

you want to send the message. Specify the lookup name of
the Destination object when the JMS connection alias uses
JNDI to retrieve administered objects. Specify the providerspecic name of the Destination when the JMS connection
alias uses the native webMethods API to connect directly to
the webMethods Broker.

destinationType

String Optional. Type of destination to which you want to

send the message. Specify one of the following:
QUEUE to send the message to a particular receiver/queue.

This is the default.

TOPIC to send the message to a topic.

Note: You need to specify a destinationType only if you

specied a connectionAliasName that uses the native
webMethods API.
stream

Object A stream for the message you want to send to the

webMethods Broker.

Output Parameters
None.
Usage Notes
When using the webMethods Broker as the JMS provider, the webMethods message
streaming feature allows you to stream large amounts of data or a large le from
a message producer to a message consumer. You can only send and receive large
messages from Integration Server when working with the webMethods Broker. For
more information about how the webMethods message streaming feature works on the
webMethods Broker, see the webMethods Broker Messaging Programmers Guide.
Large message streams cannot be sent or received as part of a transaction. If
connectionAliasName species a JMS connection alias with a transaction type of
LOCAL_TRANSACTION or XA_TRANSACTION, Integration Server throws the
exception com.wm.app.b2b.server.jms.JMSSubsystemException when it executes the
pub.jms.wmjms:sendStream service.

webMethods Integration Server Built-In Services Reference Version 9.6

475

Even Header
JMS Folder

If the connection between Integration Server and the webMethods Broker fails before the
pub.jms.wmjms:sendStream sends the entire message stream, you need to re-send the entire
stream when the connection is re-established.
See Also
pub.jms.wmjms:receiveStream

webMethods Integration Server Built-In Services Reference Version 9.6

476

Odd Header
JSON Folder

15 JSON Folder
Data Type Mapping ....................................................................................................................

478

Summary of Elements in This Folder ........................................................................................

479

webMethods Integration Server Built-In Services Reference Version 9.6

477

Even Header
JSON Folder

You use the elements in the JSON folder to convert JSON content into a document (IData
object), and a document (IData object) into JSON content.

Data Type Mapping

The following table shows how JSON data types map to Integration Server data types
during data conversion.
JSON

Integration Server

object

Document

string

String

number (integer)

Integer or Long Java wrapper. For more

information about converting JSON integers,
see the decodeIntegerAsLong input parameters in
"pub.json:jsonStreamToDocument" on page 480 and
"pub.json:jsonStringToDocument" on page 481.

number (real)

Float or Double Java wrapper. For more

information about converting real numbers,
see the decodeRealAsDouble input parameter in
"pub.json:jsonStreamToDocument" on page 480 and
"pub.json:jsonStringToDocument" on page 481.

True/False

Boolean Java wrapper

Array of JSON type

Array of Integration Server type

null

null

All others

String
Note: If an object has a toString() implementation,
Integration Server uses that implementation.
If the object does not provide a toString()
implementation, Integration Server uses Object.toString().
Object.toString() returns the class name and hexadecimal
representation of the hash code of the object, such as
"javax.namining.InitialContext@3ae6f00b".

webMethods Integration Server Built-In Services Reference Version 9.6

478

Odd Header
JSON Folder

Summary of Elements in This Folder

The following elements are available in this folder:
Element

Package and Description

pub.json:documentToJSONString

WmPublic. Converts a document (IData object) to a

JSON string.

pub.json:jsonStreamToDocument

WmPublic. Converts content from the JSON content

stream to a document (an IData object).

pub.json:jsonStringToDocument

WmPublic. Converts a JSON string to a document

(an IData object).

pub.json:documentToJSONString
WmPublic. Converts a document (IData object) to a JSON string.
Input Parameters
document

Document The document (IData object) to be converted to a JSON

string.

preyPrint

String Optional. Formats the jsonString output parameter for

human readability by adding carriage returns and indentation to
the JSON content. Set to:
true to format jsonString output variable for human readability.
false to leave the jsonString output variable in its unformaed

state. The service will not add any additional carriage returns or
indentation to the JSON content.

null to use the prettyPrint seing already in eect for the

HTTP client making the request, as follows:

If the HTTP client request includes jsonPrettyPrint=true

in the URI, JSON prey printing is in eect.
If the HTTP client request includes jsonPrettyPrint=false
in the URI, JSON prey printing is not in eect.
If the HTTP client request does not include the
jsonPrettyPrint parameter, the service uses the value of
webMethods Integration Server Built-In Services Reference Version 9.6

479

Even Header
JSON Folder

the wa.server.json.preyPrint conguration parameter.

For more information about wa.server.json.preyPrint, see
webMethods Integration Server Administrators Guide.
Output Parameters
jsonString

String JSON string resulting from the conversion of document .

Usage Notes
To turn a document in a pipeline into a JSON response to send over HTTP, the
application's service can:
1. Use pub.json:documentToJSONString to turn a document (IData object) in the pipeline into
a string of JSON content.
2. Call pub.client:http to send the JSON string as an HTTP request.
3. Set the Content-Type header eld to application/json.

pub.json:jsonStreamToDocument
WmPublic. Converts content from the JSON content stream to a document (an IData
object).
Input Parameters
jsonStream

java.io.InputStream JSON content in an input stream to convert

to a document (an IData object).

decodeRealAsDouble

String Optional. Converts real numbers from jsonStream to

either a Float or Double Java wrapper type. Set to:
true to convert real numbers to Double Java wrapper types.

This is the default.

false to convert real numbers to Float Java wrapper types.

Note: The decodeRealAsDouble parameter overrides the value

specied by the wa.server.json.decodeRealAsDouble
server conguration parameter. If no value is supplied for
decodeRealAsDouble , Integration Serveruses the value set in
wa.server.json.decodeRealAsDouble. For more information
about wa.server.json.decodeRealAsDouble, see webMethods
Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

480

Odd Header
JSON Folder

decodeIntegerAsLong

String Optional. Converts integers from jsonStream to either a

Long or Integer Java wrapper type. Set to:
true to convert integers to Long Java wrapper types. This is

the default.

false to convert integers to Integer Java wrapper types.

Note: The decodeRealAsDouble parameter overrides the value

specied by the wa.server.json.decodeIntegerAsLong
server conguration parameter. If no value is supplied
for decodeIntegerAsLong , Integration Server uses the value
specied in the wa.server.json.decodeIntegerAsLong
property. For more information about
wa.server.json.decodeIntegerAsLong, see webMethods
Integration Server Administrators Guide.
Output Parameters
document

Document Document (IData object) resulting from the

conversion of jsonStream .

Usage Notes
The JSON content handler in Integration Server creates a jsonStream object in the
pipeline when a client sends a request to Integration Server using the application/json
Content-Type. The pub.json:jsonStreamToDocument service converts the jsonStream into a
document (IData object) so you can use the elements from jsonStream in a ow service.
If wa.server.hp.jsonFormat is set to stream, Integration Server places a jsonStream
variable in the pipeline when it receives an HTTP request containing JSON content. You
can then use pub.json:jsonStreamToDocument to parse jsonStream into pipeline variables. For
more information about wa.server.hp.jsonFormat, see webMethods Integration Server
Administrators Guide.

pub.json:jsonStringToDocument
WmPublic. Converts a JSON string to a document (an IData object).
Input Parameters
jsonString

String JSON content in a string to convert to a document

(IData object).

decodeRealAsDouble

String Optional. Converts real numbers from jsonString to

either a Float or Double Java wrapper type. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

481

Even Header
JSON Folder

true to convert real numbers to Double Java wrapper types.

This is the default.

false to convert real numbers to Float Java wrapper types.

Note: The decodeRealAsDouble parameter overrides the value

specied by the wa.server.json.decodeRealAsDouble
server conguration parameter. If no value is supplied for
decodeRealAsDouble , Integration Serveruses the value set in
wa.server.json.decodeRealAsDouble. For more information
about wa.server.json.decodeRealAsDouble, see webMethods
Integration Server Administrators Guide.
decodeIntegerAsLong

String Optional. Converts integers from jsonString to either a

Long or Integer Java wrapper type. Set to:
true to convert integers to Long Java wrapper types. This is

the default.

false to convert integers to Integer Java wrapper types.

Note: The decodeRealAsDouble parameter overrides the value

specied by the wa.server.json.decodeIntegerAsLong
server conguration parameter. If no value is supplied
for decodeIntegerAsLong , Integration Server uses the value
specied in the wa.server.json.decodeIntegerAsLong
property. For more information about
wa.server.json.decodeIntegerAsLong, see webMethods
Integration Server Administrators Guide.
Output Parameters
document

Document Document (IData object) resulting from the

conversion of jsonString .

webMethods Integration Server Built-In Services Reference Version 9.6

482

Odd Header
List Folder

16 List Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

484

483

Even Header
List Folder

You use the elements in the list folder to retrieve, replace, or add elements in an Object
List, Document List, String List, or Vector. You also use list services to convert String
Lists to Document Lists or a Vector to an Array.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.list:addItemToVector

WmPublic. Adds an item or a list of items to a

java.util.Vector object.

pub.list:appendToDocumentList

WmPublic. Adds documents to a document

list.

pub.list:appendToStringList

WmPublic. Adds Strings to a String list.

pub.list:sizeOfList

WmPublic. Returns the number of elements in

a list.

pub.list:stringListToDocumentList

WmPublic. Converts a String list to a

document list.

pub.list:vectorToArray

WmPublic. Converts a java.util.Vector object

to an array.

pub.list:addItemToVector
WmPublic. Adds an item or a list of items to a java.util.Vector object.
Input Parameters
vector

java.util.Vector Optional. The vector object to which you want to

add an item or list of items. If no value is specied, the service
creates a new java.util.Vector object to which the item(s) will
be added.

item

Object Optional. Item to be added to the vector object.

Note: You can use either item or itemList to specify the input
object. If both item and itemList input parameters are specied,

webMethods Integration Server Built-In Services Reference Version 9.6

484

Odd Header
List Folder

the item as well as the list of items will be added to the vector
object.
itemList

Object[ ]Optional. List of items to be added to the vector object.

addNulls

String Optional. Species whether a null item can be added to

the vector object. Set to:
false to prevent null values from being added to the vector

object. This is the default.

true to allow null values to be added to the vector object.

Output Parameters
vector

java.util.Vector Updated vector object with the list of items

added or an empty vector in case no items are added.

Usage Notes
Either of the optional input parameters, item or itemList , is required.

pub.list:appendToDocumentList
WmPublic. Adds documents to a document list.
Input Parameters
toList

Document List Optional. List to which you want to append

documents. If you do not specify toList , the service creates a
new list.

fromList

Document List Optional. Documents you want to append to the

end of toList .

fromItem

Document Optional. Document you want to append to the end

of toList . If you specify both fromList and fromItem , the service
adds the document specied in fromItem after the documents
in fromList .

webMethods Integration Server Built-In Services Reference Version 9.6

485

Even Header
List Folder

Output Parameters
toList

Document List The toList document list with the documents in

fromList and fromItem appended to it.

Usage Notes
The documents contained in fromList and fromItem are not actually appended as entries
to toList . Instead, references to the documents in fromList and fromItem are appended
as entries to toList . Consequently, any changes made to the documents in fromList and
fromItem also aect the resulting toList .

pub.list:appendToStringList
WmPublic. Adds Strings to a String list.
Input Parameters
toList

String List Optional. List to which you want to append Strings.

If the value of toList is null, a null pointer exception error is
thrown. If you do not specify toList , the service creates a new
list.

fromList

String List Optional. List of Strings to add to toList . Strings are

added after the entries of toList .

fromItem

String Optional. String you want to append to the end of toList .

If you specify both fromList and fromItem , the service adds
the String specied in fromItem after the Strings specied in
fromList .

Output Parameters
toList

String List The toList String list with the Strings from fromList
and fromItem appended to it.

Usage Notes
The Strings contained in fromList and fromItem are not actually appended as entries to
toList . Instead, references to the Strings in fromList and fromItem are appended as entries
to toList . Consequently, any changes made to the Strings in fromList and fromItem also
aect the resulting toList .

webMethods Integration Server Built-In Services Reference Version 9.6

486

Odd Header
List Folder

pub.list:sizeOfList
WmPublic. Returns the number of elements in a list.
Input Parameters
fromList

Document List, String List, or Object List Optional. List whose size
you want to discover. If fromList is not specied, the service
returns a size of 0.

Output Parameters
size

String Number of entries in fromList .

fromList

Document List, String List, or Object List Original list.

Usage Notes
For example, if fromList consists of:
fromList [0] = "a"
fromList [1] = "b"
fromList [2] = "c"
The result would be:
size ="3"

pub.list:stringListToDocumentList
WmPublic. Converts a String list to a document list.
Input Parameters
fromList

String List Optional. List of Strings (a String[ ]) that you want

to convert to a list of documents (an IData[ ]). If fromList is not
specied, the service returns a zero length array for toList .

key

String Optional. Key name to use in the generated document

list.

webMethods Integration Server Built-In Services Reference Version 9.6

487

Even Header
List Folder

Output Parameters
toList

Document List Resulting document list.

Usage Notes
Creates a document list containing one document for each element in the fromList . Each
document will contain a single String element named key .
For example, if fromList consists of:
fromList [0] = "a"
fromList [1] = "b"
fromList [2] = "c"
key = "myKey"
The result would be:

pub.list:vectorToArray
WmPublic. Converts a java.util.Vector object to an array.
Input Parameters
vector

java.util.Vector The object to be converted to an array.

stronglyType

String Optional. If this option is specied, the service expects

all items in the vector to have the same Java type as the rst
non-null item in the vector. If the service detects an item of a
dierent type, an error is thrown.
Set to:
false to convert the vector to an object array. This is the

default.

webMethods Integration Server Built-In Services Reference Version 9.6

488

Odd Header
List Folder

true to convert the vector to a strongly typed array holding

the same type of objects.

Output Parameters
array

Object[ ] Converted object array.

webMethods Integration Server Built-In Services Reference Version 9.6

489

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

490

Odd Header
Math Folder

17 Math Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

492

491

Even Header
Math Folder

You use the elements in the math folder to perform mathematical operations on stringbased numeric values.
Note: Services that operate on integer values use Java's long data type (64-bit, two's
complement). Services that operate on oat values use Java's double data type (64-bit
IEEE 754). If extremely precise calculations are critical to your application, you should
write your own Java services to perform math functions.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.math:absoluteValue

WmPublic. Returns the absolute value of the input

number.

pub.math:addFloatList

WmPublic. Adds a list of oating point numbers

(represented in a string list) and returns the sum.

pub.math:addFloats

WmPublic. Adds one oating point number

(represented as a String) to another and returns the
sum.

pub.math:addIntList

WmPublic. Adds a list of integers (represented in a

String list) and returns the sum.

pub.math:addInts

WmPublic. Adds one integer (represented as a String)

to another and returns the sum.

pub.math:addObjects

WmPublic. Adds one java.lang.Number object to

another and returns the sum.

pub.math:divideFloats

WmPublic. Divides one oating point number

(represented as a String) by another (num1/num2 ) and
returns the quotient.

pub.math:divideInts

WmPublic. Divides one integer (represented as a

String) by another (num1/num2 ) and returns the
quotient.

pub.math:divideObjects

WmPublic. Divides one java.lang.Number object by

another (num1/num2 ) and returns the quotient.

webMethods Integration Server Built-In Services Reference Version 9.6

492

Odd Header
Math Folder

Element

Package and Description

pub.math:max

WmPublic. Returns the largest number from a list of

numbers.

pub.math:min

WmPublic. Returns smallest number from a list of

numbers.

pub.math:multiplyFloatList

WmPublic. Multiplies a list of oating point numbers

(represented in a String list) and returns the product.

pub.math:multiplyFloats

WmPublic. Multiples one oating point number

(represented as String) by another and returns the
product.

pub.math:multiplyIntList

WmPublic. Multiplies a list of integers (represented in

a String list) and returns the product.

pub.math:multiplyInts

WmPublic. Multiplies one integer (represented as a

String) by another and returns the product.

pub.math:multiplyObjects

WmPublic. Multiplies one java.lang.Number object by

another and returns the product.

pub.math:randomDouble

WmPublic. Returns the next pseudorandom,

uniformly distributed double between 0.0 and 1.0.

pub.math:roundNumber

WmPublic. Returns a rounded number.

pub.math:subtractFloats

WmPublic. Subtracts one oating point number

(represented as a String) from another and returns the
dierence.

pub.math:subtractInts

WmPublic. Subtracts one integer (represented as a

String) from another and returns the dierence.

pub.math:subtractObjects

WmPublic. Subtracts one java.lang.Number object

from another and returns the dierence.

pub.math:toNumber

WmPublic. Converts a string to numeric data type.

webMethods Integration Server Built-In Services Reference Version 9.6

493

Even Header
Math Folder

pub.math:absoluteValue
WmPublic. Returns the absolute value of the input number.
Input Parameters
String Number whose absolute value is to be returned.

num
Output Parameters
positiveNumber

String Absolute value of the input number.

pub.math:addFloatList
WmPublic. Adds a list of oating point numbers (represented in a string list) and
returns the sum.
Input Parameters
numList

String List Numbers (oating point numbers represented in a string list) to

add.

Output Parameters
value

String Sum of the numbers in numList . If a sum cannot be produced, value

contains one of the following:
Value

Description

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that overows

the representable range of a oat type.

0.0

The computation produces a value that underows the

representable range of a oat type (for example, adding a
number to innity).

webMethods Integration Server Built-In Services Reference Version 9.6

494

Odd Header
Math Folder

NaN

The computation produces a value that cannot be

represented as a number (for example, any operation that
uses NaN as input, such as 10.0 + NaN = NaN).

Usage Notes
Make sure the strings that are passed to the service in numList are in a locale-neutral
format (that is, using the paern -



.

). Passing locally formaed strings may result
in unexpected results. For example, calling pub.math:addFloats in a German locale with the
arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:addFloats
WmPublic. Adds one oating point number (represented as a String) to another and
returns the sum.
Input Parameters
num1

String Number to add.

num2

String Number to add.

precision

String Optional. Number of decimal places to which the sum will be

rounded. The default value is null.
The precision parameter, if specied, will override the behavior set by
the wa.server.math.oatOperation.mode property. For information
about the wa.server.math.oatOperation.mode property, see the
webMethods Integration Server Administrators Guide.

Output Parameters
value

String Sum of the numbers in num1 and num2 . If a sum cannot be

produced, value contains one of the following:
Value

Description

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that overows

the representable range of a oat type.

webMethods Integration Server Built-In Services Reference Version 9.6

495

Even Header
Math Folder

0.0

The computation produces a value that underows the

representable range of a oat type (for example, adding a
number to innity).

NaN

The computation produces a value that cannot be

represented as a number (for example, any operation that
uses NaN as input, such as 10.0 + NaN = NaN).

Usage Notes
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.
Use the wa.server.math.oatOperation.mode property to specify whether
the pub.math:addFloats service return the exact result of an operation involving
two oating point numbers, the result as calculated by the JVM, or the
result based on a xed number of decimal places. For information about the
wa.server.math.oatOperation.mode property, see the webMethods Integration Server
Administrators Guide.

pub.math:addIntList
WmPublic. Adds a list of integers (represented in a String list) and returns the sum.
Input Parameters
numList

String List Numbers (integers represented as Strings) to add.

Output Parameters
value

String Sum of the numbers in numList .

Usage Notes
Make sure the strings that are passed to the service in numList are in a locale-neutral
format (that is, using the paern -



.

). Passing locally formaed strings may result
in unexpected results. For example, calling pub.math:addFloats in a German locale with the
arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

webMethods Integration Server Built-In Services Reference Version 9.6

496

Odd Header
Math Folder

pub.math:addInts
WmPublic. Adds one integer (represented as a String) to another and returns the sum.
Input Parameters
num1

String Number (integer represented as a String) to add.

num2

String Number (integer represented as a String) to add.

Output Parameters
String Sum of num1 and num2 .

value
Usage Notes

Make sure the result of your calculation is less than 64 bits in width (the maximum
width for the long data type). If the result exceeds this limit, it will generate a data
overow.
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:addObjects
WmPublic. Adds one java.lang.Number object to another and returns the sum.
Input Parameters
num1

java.lang.Number Number to add. See the Usage Notes for supported subclasses.

num2

java.lang.Number Number to add. See the Usage Notes for supported subclasses.

Output Parameters
value

java.lang.Number Sum of the numeric values of num1 and num2 .

webMethods Integration Server Built-In Services Reference Version 9.6

497

Even Header
Math Folder

Usage Notes
This service accepts the following sub-classes of java.lang.Number: java.lang.Byte,
java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short.
This service applies the following rules for binary numeric promotion to the operands in
order:
If either operand is of type Double, the other is converted to Double.
Otherwise, if either operand is of type Float, the other is converted to Float.
Otherwise, if either operand is of type Long, the other is converted to Long.
Otherwise, both operands are converted to type Integer.
These promotion rules mirror the Java rules for numeric promotion of numeric types.

pub.math:divideFloats
WmPublic. Divides one oating point number (represented as a String) by another
(num1/num2 ) and returns the quotient.
Input Parameters
num1

String Number (oating point number represented as a String) that is the

dividend.

num2

String Number (oating point number represented as a String) that is the

divisor.

precision

String Optional. Number of decimal places to which the quotient will be

rounded. The default value is null.
The precision parameter, if specied, will override the behavior set by the
wa.server.math.oatOperation.mode property. For information about
the wa.server.math.oatOperation.mode property, see the webMethods
Integration Server Administrators Guide.

Output Parameters
value

String The quotient of num1 / num2 . If a quotient cannot be produced,

value contains one of the following:
Value

Description

webMethods Integration Server Built-In Services Reference Version 9.6

498

Odd Header
Math Folder

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that overows

the representable range of a oat type.

0.0

The computation produces a value that underows the

representable range of a oat type (for example, dividing a
number by innity).

NaN

The computation produces a value that cannot be

represented as a number (for example, the result of an illegal
operation such as dividing zero by zero or any operation that
uses NaN as input, such as 10.0 + NaN = NaN).

Usage Notes
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.
Use the wa.server.math.oatOperation.mode property to specify whether
the pub.math:divideFloats service return the exact result of an operation involving
two oating point numbers, the result as calculated by the JVM, or the
result based on a xed number of decimal places. For information about the
wa.server.math.oatOperation.mode property, see the webMethods Integration Server
Administrators Guide.

pub.math:divideInts
WmPublic. Divides one integer (represented as a String) by another (num1/num2 ) and
returns the quotient.
Input Parameters
num1

String Number (integer represented as a String) that is the dividend.

num2

String Number (integer represented as a String) that is the divisor.

Output Parameters
value

String The quotient of num1 / num2 .

webMethods Integration Server Built-In Services Reference Version 9.6

499

Even Header
Math Folder

Usage Notes
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:divideObjects
WmPublic. Divides one java.lang.Number object by another (num1/num2 ) and returns
the quotient.
Input Parameters
num1

java.lang.Number Number that is the dividend. See the Usage Notes for
supported sub-classes.

num2

java.lang.Number Number that is the divisor. See the Usage Notes for
supported sub-classes.

Output Parameters
value

java.lang.Number Quotient of num1 / num2 .

Usage Notes
This service accepts the following sub-classes of java.lang.Number: java.lang.Byte,
java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short.
This service applies the following rules for binary numeric promotion to the operands in
order:
If either operand is of type Double, the other is converted to Double.
Otherwise, if either operand is of type Float, the other is converted to Float.
Otherwise, if either operand is of type Long, the other is converted to Long.
Otherwise, both operands are converted to type Integer.
These promotion rules mirror the Java rules for numeric promotion of numeric types.

pub.math:max
WmPublic. Returns the largest number from a list of numbers.

webMethods Integration Server Built-In Services Reference Version 9.6

500

Odd Header
Math Folder

Input Parameters
numList

String List List of numbers from which the largest number is to be

returned.

Output Parameters
maxValue

String Largest number from the list of numbers.

pub.math:min
WmPublic. Returns smallest number from a list of numbers.
Input Parameters
numList

String List List of numbers from which the smallest number is to be

returned.

Output Parameters
minValue

String Smallest number from the list of numbers.

pub.math:multiplyFloatList
WmPublic. Multiplies a list of oating point numbers (represented in a String list) and
returns the product.
Input Parameters
numList

String List Numbers (oating point numbers represented as Strings) to

multiply.

Output Parameters
value

String Product of the numbers in numlist . If a product cannot be

produced, value contains one of the following:

webMethods Integration Server Built-In Services Reference Version 9.6

501

Even Header
Math Folder

Value

Description

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that overows

the representable range of a oat type.

0.0

The computation produces a value that underows the

representable range of a oat type (for example, multiplying
a number by innity).

NaN

The computation produces a value that cannot be

represented as a number (for example, the result of an illegal
operation such as multiplying zero by zero or any operation
that uses NaN as input, such as 10.0 + NaN = NaN).

Usage Notes
Make sure the strings that are passed to the service in numList are in a locale-neutral
format (that is, using the paern -



.

). Passing locally formaed strings may result
in unexpected results. For example, calling pub.math:addFloats in a German locale with the
arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:multiplyFloats
WmPublic. Multiples one oating point number (represented as String) by another and
returns the product.
Input Parameters
num1

String Number (oating point number represented as a String) to

multiply.

num2

String Number (oating point number represented as a String) to

multiply.

precision

String Optional. Number of decimal places to which the product will be

rounded. The default value is null.
The precision parameter, if specied, will override the behavior set by
the wa.server.math.oatOperation.mode property. For information
about the wa.server.math.oatOperation.mode property, see the
webMethods Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

502

Odd Header
Math Folder

Output Parameters
value

String Product of the numeric values of num1 and num2 . If a product

cannot be produced, value contains one of the following:
Value

Description

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that

overows the representable range of a oat type.

0.0

The computation produces a value that underows

the representable range of a oat type (for example,
multiplying a number by innity).

NaN

The computation produces a value that cannot be

represented as a number (for example, the result of an
illegal operation such as multiplying zero by zero or any
operation that uses NaN as input, such as 10.0 + NaN =
NaN).

Usage Notes
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.
Use the wa.server.math.oatOperation.mode property to specify whether the
pub.math:multiplyFloats service return the exact result of an operation involving two oating
point numbers, the result as calculated by the JVM, or the result based on a xed
number of decimal places. See webMethods Integration Server Administrators Guide for
more information about the wa.server.math.oatOperation.mode property.

pub.math:multiplyIntList
WmPublic. Multiplies a list of integers (represented in a String list) and returns the
product.

webMethods Integration Server Built-In Services Reference Version 9.6

503

Even Header
Math Folder

Input Parameters
String List Numbers (oating point numbers represented as Strings) to
multiply.

numList

Output Parameters
String Product of the numbers in numList .

value
Usage Notes

Make sure the result of your calculation is less than 64 bits in width (the maximum
width for the long data type). If the result exceeds this limit, it will generate a data
overow.
Make sure the strings that are passed to the service in numList are in a locale-neutral
format (that is, using the paern -



.

). Passing locally formaed strings may result
in unexpected results. For example, calling pub.math:addFloats in a German locale with the
arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:multiplyInts
WmPublic. Multiplies one integer (represented as a String) by another and returns the
product.
Input Parameters
num1

String Number (integer represented as a String) to multiply.

num2

String Number (integer represented as a String) to multiply.

Output Parameters
value

String Product of num1 and num2 .

Usage Notes
Make sure the result of your calculation is less than 64 bits in width (the maximum
width for the long data type). If the result exceeds this limit, it will generate a data
overow.
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
webMethods Integration Server Built-In Services Reference Version 9.6

504

Odd Header
Math Folder

may result in unexpected results. For example, calling pub.math:addFloats in a German

locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:multiplyObjects
WmPublic. Multiplies one java.lang.Number object by another and returns the product.
Input Parameters
num1

java.lang.Number Number to multiply. See the Usage Notes for supported

sub-classes.

num2

java.lang.Number Number to multiply. See the Usage Notes for supported

sub-classes.

Output Parameters
value

java.lang.Number Product of num1 and num2 .

Usage Notes
This service accepts the following sub-classes of java.lang.Number: java.lang.Byte,
java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short.
This service applies the following rules for binary numeric promotion to the operands in
order:
If either operand is of type Double, the other is converted to Double.
Otherwise, if either operand is of type Float, the other is converted to Float.
Otherwise, if either operand is of type Long, the other is converted to Long.
Otherwise, both operands are converted to type Integer.
These promotion rules mirror the Java rules for numeric promotion of numeric types.

pub.math:randomDouble
WmPublic. Returns the next pseudorandom, uniformly distributed double between 0.0
and 1.0.
Random number generators are often referred to as pseudorandom number generators
because the numbers produced tend to repeat themselves over time.

webMethods Integration Server Built-In Services Reference Version 9.6

505

Even Header
Math Folder

Input Parameters
None.
Output Parameters
number

String Generated random number.

pub.math:roundNumber
WmPublic. Returns a rounded number.
Input Parameters
num

String Number to be rounded.

numberOfDigits

String Species the number of digits to which you want to round

the number.

roundingMode

String Optional. Species the rounding method.

Valid values for the roundingMode parameter are RoundHalfUp,
RoundUp, RoundDown, RoundCeiling, RoundFloor,
RoundHalfDown, and RoundHalfEven. The default value is
RoundHalfUp.

Output Parameters
roundedNumber

String The rounded number.

pub.math:subtractFloats
WmPublic. Subtracts one oating point number (represented as a String) from another
and returns the dierence.
Input Parameters
num1

String Number (oating point number represented as a String).

webMethods Integration Server Built-In Services Reference Version 9.6

506

Odd Header
Math Folder

num2

String Number (oating point number represented as a String) to

subtract from num1 .

precision

String Optional. Number of decimal places to which the dierence will

be rounded. The default value is null.
The precision parameter, if specied, will override the behavior set by
the wa.server.math.oatOperation.mode property. For information
about the wa.server.math.oatOperation.mode property, see the
webMethods Integration Server Administrators Guide.

Output Parameters
value

String Dierence of num1 - num2 . If a dierence cannot be produced,

value contains one of the following:
Value

Description

Infinity

The computation produces a positive value that overows

the representable range of a oat type.

Infinity

The computation produces a negative value that overows

the representable range of a oat type.

0.0

The computation produces a value that underows

the representable range of a oat type (for example,
subtracting a number from innity).

NaN

The computation produces a value that cannot be

represented as a number (for example, the result of an
illegal operation such as multiplying zero by zero or any
operation that uses NaN as input, such as 10.0 - NaN =
NaN).

Usage Notes
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.
Use the wa.server.math.oatOperation.mode property to specify whether the
pub.math:subtractFloats service return the exact result of an operation involving
two oating point numbers, the result as calculated by the JVM, or the result
based on a xed number of decimal places. For more information about the

webMethods Integration Server Built-In Services Reference Version 9.6

507

Even Header
Math Folder

wa.server.math.oatOperation.mode property, see webMethods Integration Server

Administrators Guide

pub.math:subtractInts
WmPublic. Subtracts one integer (represented as a String) from another and returns the
dierence.
Input Parameters
num1

String Number (integer represented as a String).

num2

String Number (integer represented as a String) to subtract from num1 .

Output Parameters
value

String Dierence of num1 - num2 .

Usage Notes
Make sure the result of your calculation is less than 64 bits in width (the maximum
width for the long data type). If the result exceeds this limit, it will generate a data
overow.
Make sure the strings that are passed to the service in num1 andnum2 are in a localeneutral format (that is, using the paern -



.

). Passing locally formaed strings
may result in unexpected results. For example, calling pub.math:addFloats in a German
locale with the arguments 1,23 and 2,34 will result in the value 357, not 3.57 or 3,57.

pub.math:subtractObjects
WmPublic. Subtracts one java.lang.Number object from another and returns the
dierence.
Input Parameters
num1

java.lang.Number Number. See the Usage Notes for supported sub-classes.

num2

java.lang.Number Number to subtract from num1 . See Usage Notes for

supported sub-classes.

webMethods Integration Server Built-In Services Reference Version 9.6

508

Odd Header
Math Folder

Output Parameters
value

java.lang.Number Dierence of num1 - num2 .

Usage Notes
This service accepts the following sub-classes of java.lang.Number: java.lang.Byte,
java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short.
This service applies the following rules for binary numeric promotion to the operands.
The following rules are applied in order:
If either operand is of type Double, the other is converted to Double.
Otherwise, if either operand is of type Float, the other is converted to Float.
Otherwise, if either operand is of type Long, the other is converted to Long.
Otherwise, both operands are converted to type Integer.
These promotion rules mirror the Java rules for numeric promotion of numeric types.

pub.math:toNumber
WmPublic. Converts a string to numeric data type.
Input Parameters
num

String Number (represented as a string) to be converted to numeric

format.

convertAs

String Optional. Species the Java numeric data type to which the num
parameter is to be converted.
Valid values for the convertAs parameter
are java.lang.Double, java.lang.Float,
java.lang.Integer,java.math.BigDecimal,java.math.BigInteger,
java.lang.Long. The default value is java.lang.Double.

Output Parameters
num

java.lang.Number Converted numeric object.

webMethods Integration Server Built-In Services Reference Version 9.6

509

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

510

Odd Header
Metadata Folder

18 Metadata Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

512

511

Even Header
Metadata Folder

You use the elements in the metadata folder to publish metadata about Integration
Server packages and administrative assets to the CentraSite shared registry.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.metadata.assets:publishPackages

WmAssetPublisher. Publishes metadata about

Integration Server packages and administrative
assets to the CentraSite shared registry.

pub.metadata.assets:publishPackages
WmAssetPublisher. Publishes metadata about Integration Server packages, the
supported assets in the package, and administrative assets to the CentraSite shared
registry.
Input Parameters
packages

String A comma-separated list of Integration Server packages

about which you want to publish metadata.

includeServerAssets

String Whether to publish information about Integration Server

administrative assets to the CentraSite shared registry. Specify
one of the following values:
True to indicate that information about administrative assets

will be published to the CentraSite shared registry. This is the

default.
False to indicate that information about administrative

assets will not be published to the CentraSite shared registry.

Output Parameters
None.
Usage Notes
Use the pub.metadata.assets:publishPackages service to publish metadata about
Integration Server packages and administrative assets to CentraSite on a scheduled
basis. To schedule this service, create a scheduled task that executes this service.

webMethods Integration Server Built-In Services Reference Version 9.6

512

Odd Header
Metadata Folder

For instructions about creating a scheduled task, see webMethods Integration Server
Administrators Guide
For the pub.metadata.assets:publishPackages service to execute successfully, Integration
Server must be congured to connect to CentraSite and the CentraSite connection
must be available. If Integration Server is not congured to connect to CentraSite
or the connection is not available, Integration Server returns a ServiceException.
For information about conguring the connection to CentraSite, see webMethods
Integration Server Administrators Guide.
When this service executes, it publishes metadata using Integration Server
credentials.

webMethods Integration Server Built-In Services Reference Version 9.6

513

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

514

Odd Header
MIME Folder

19 MIME Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

516

515

Even Header
MIME Folder

You use the elements in the mime folder to create MIME messages and extract
information from MIME messages.

Summary of Elements in this Folder

The following elements are available in this folder:
Service

Function

pub.mime:addBodyPart

WmPublic. Adds a body part (header elds

and content) to a specied MIME object.

pub.mime:addMimeHeader

WmPublic. Adds one or more header elds

to a specied MIME object.

pub.mime:createMimeData

WmPublic. Creates a MIME object.

pub.mime:getBodyPartContent

WmPublic. Retrieves the content (payload)

from the specied MIME object.

pub.mime:getBodyPartHeader

WmPublic. Returns the list of header elds

for the specied body part.

pub.mime:getContentType

WmPublic. Returns the value of the ContentType message header from the specied
MIME object.

pub.mime:getEnvelopeStream

WmPublic. Generates an InputStream

representation of a MIME message from a
specied MIME object.

pub.mime:getMimeHeader

WmPublic. Returns the list of message

headers from a specied MIME object.

pub.mime:getNumParts

WmPublic. Returns the number of body

parts in the specied MIME object.

pub.mime:getPrimaryContentType

WmPublic. Returns the top-level portion of a

MIME object's Content-Type value.

pub.mime:getSubContentType

WmPublic. Returns the sub-type portion of a

MIME object's Content-Type value.

webMethods Integration Server Built-In Services Reference Version 9.6

516

Odd Header
MIME Folder

Service

Function

pub.mime:mergeHeaderAndBody

WmPublic. Concatenates the contents

of the header and body returned by the
pub.client:http service.

pub.mime:addBodyPart
WmPublic. Adds a body part (header elds and content) to a specied MIME object.
Input Parameters
mimeData

Document MIME object to which you want to add a body part.

(This IData object is produced by pub.mime:createMimeData.)

content

java.io.InputStream or Object Content that you want to add to the

MIME object. content can be an InputStream or another MIME
object. Use an InputStream to add an ordinary payload. Use a
MIME object to add a payload that is itself a MIME message.

isEnvStream

String Flag that species whether content is to be treated as a

MIME entity.
Important: This parameter is only used if content is an InputStream.
Set this parameter to one of the following values:
yes to treat content as a MIME entity. addBodyPart will strip
out the header elds from the top of content and add them to
mimeData as part headers. The remaining data will be treated
as the payload.

Note: addBodyPart assumes that all data up to the rst blank line
represents the entity's header elds.
no to treat content as an ordinary payload.

mimeHeader

Document Species the part headers that you want to add with
this body part. Key names represent the names of the header
elds. The values of the keys represent the values of the header
elds.
For example, if you wanted to add the following header elds:
X-Doctype: RFQ
X-Severity: 10

webMethods Integration Server Built-In Services Reference Version 9.6

517

Even Header
MIME Folder

You would set mimeHeader as follows:

Key

Value

X-Doctype

RFQ

X-Severity

10

Be aware that the following MIME headers are automatically

inserted by pub.mime:getEnvelopeStream when it generates the
MIME message:
Message-ID
MIME-Version

Additionally, you use the content , encoding , and description

parameters to set the following elds:
Content-Type
Content-Transfer-Encoding
Content-Description

If you set these header elds in mimeHeader and you create a

single-part message, the values in contenype , encoding , and
description, if specied, will override those in mimeHeader . See
usage notes.
contenype

String Optional. The value of the Content-Type header for this

body part. For single-part messages, this value overrides the
Content-Type value in mimeHeader , if one is present. Defaults to
text/plain.
See usage notes.

encoding

String Optional. Species how the body part is to be encoded for

transport and sets the value of the Content-Transfer-Encoding
header. For single-part messages, this value overrides the
Content-Transfer-Encoding value in mimeHeader , if one is
present. Defaults to 7bit.
See usage notes.
Note: This parameter determines how the payload is to be encoded
for transport. When you add a payload to mimeData , it should be
in its original format. The pub.mime:getEnvelopeStream service will
perform the encoding (as specied by encoding ) when it generates
the nal MIME message.
Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

518

Odd Header
MIME Folder

7bit to specify that content is 7-bit, line-oriented text that needs

no encoding. This is the default.
8bit to specify that content is 8-bit, line-oriented text that needs
no encoding.

Note: This encoding value is not recommended for messages

that will be transported via SMTP over the Internet, because
the data can be altered by intervening mail servers that can't
accommodate 8-bit text. To safely transport 8-bit text, use
quoted-printable encoding instead.
binary to specify that content contains binary information that
needs no encoding.

Note: This encoding value is not recommended for messages

that will be transported via SMTP over the Internet, because
the data can be altered by intervening mail servers that can't
accommodate binary data. To safely transport binary data, use
base64 encoding instead.
quoted-printable to specify that content contains 7 or 8-bit,

line-oriented text that you want to encode using the quotedprintable encoding scheme.

base64 to specify that content contains an arbitrary sequence

of octets that you want to encode using the base64 encoding
scheme.
uuencode to specify that content contains an arbitrary sequence

of octets that you want to encode using the uuencode encoding

scheme.
description

String Optional. Species the value of the Content-Description

header for this body part.

multipart

String Optional. Flag that determines how addBodyPart behaves if

mimeData already contains one or more body parts.
By default, addBodyPart simply appends a new body part to
mimeData if it already contains a payload. (This allows you to
construct multi-part messages.) However, you can override
this behavior if you want to either replace the existing payload
with the new body part or throw an exception under these
circumstances (see replace parameter, below).
Set to:
yes to append a new body part to mimeData . This is the
default.

webMethods Integration Server Built-In Services Reference Version 9.6

519

Even Header
MIME Folder

no to replace the existing payload with the new body part.

(Depending on the value of replace , this seing may cause

addBodyPart to throw an exception.)
replace

String Optional. Flag that species whether addBodyPart replaces

the existing payload or throws an exception when it receives
a mimeData that already contains a payload. This parameter is
only used when multipart is set to no.
Set to:
yes to replace the existing payload with the new body part.

This is the default.

no to throw an exception.

Output Parameters
mimeData

Document MIME object to which the body part was added.

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
The way in which the contenype and encoding parameters are applied depends on
whether the nished message is single-part or multipart.
For single-part messages:
contenype species the Content-Type for the entire MIME message. It overrides
any value assigned to the Content-Type header in mimeHeader . If Content-Type is
not specied in contenype or mimeHeader , the value of the Content-Type header
defaults to text/plain.
encoding species the Content-Transfer-Encoding for the entire MIME message.
It overrides any value assigned to the Content-Transfer-Encoding header
in mimeHeader . If Content-Transfer-Encoding is not specied in encoding or
mimeHeader , the value of the Content-Transfer-Encoding header defaults to 7bit.
For multipart messages:
contenype species the Content-Type for an individual body part. The ContentType for the entire MIME message is automatically set to multipart/mixed, or to
multipart/subType if a subtype was specied when the MIME object was created. See
pub.mime:createMimeData.
encoding species the Content-Transfer-Encoding for an individual body part. The
Content-Transfer-Encoding header in mimeHeader , if present, species the encoding
for the entire MIME message. If Content-Transfer-Encoding is not specied in
mimeHeader , or if the specied value is not valid for a multipart message, the value of

webMethods Integration Server Built-In Services Reference Version 9.6

520

Odd Header
MIME Folder

the Content-Transfer-Encoding header defaults to 7bit. (7bit, 8bit, and binary are the
only encoding values valid for multipart messages.)
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:getBodyPartContent
pub.mime:addMimeHeader
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:build_SimpleMIME
samples.mime:build_MultipartMIME

pub.mime:addMimeHeader
WmPublic. Adds one or more header elds to a specied MIME object.
Input Parameters
mimeData

Document MIME object to which you want the header

elds added. (This IData object is produced by
pub.mime:createMimeData.)

mimeHeader

Document Header elds that you want to add to the MIME

object. Key names represent the names of the header elds.
The values of the keys represent the values of the header
elds. For example, to add the following header elds:
X-Doctype: RFQ
X-Severity: 10

You would set mimeHeader as follows:

Key

Description

X-Doctype

RFQ

X-Severity

10

webMethods Integration Server Built-In Services Reference Version 9.6

521

Even Header
MIME Folder

Be aware that the following MIME headers are automatically

inserted by pub.mime:getEnvelopeStream when it generates the
MIME message:
Message-ID
MIME-Version

If you set these values in mimeHeader ,

pub.mime:getEnvelopeStream will overwrite them at run time.
Output Parameters
mimeData

Document MIME object to which the header elds were added.

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
If you add MIME headers before you add multiple body parts, the header elds will
be added to each of the body parts. If you do not want this behavior, either drop
mimeHeader from the pipeline immediately after you execute addMimeHeader, or invoke
addMimeHeader after you've added all body parts to the MIME object.
Be aware that the contenype and encoding parameters used by the pub.mime:addBodyPart
service will override any Content-Type or Content-Transfer-Encoding seings in
mimeData . Moreover, in certain cases, the pub.mime:getEnvelopeStream will override these
seings when it generates a multipart message. For information about how the ContentType or Content-Transfer-Encoding headers are derived at run time, see the Usage
Notes under pub.mime:addBodyPart.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:getMimeHeader
pub.mime:addBodyPart
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:build_SimpleMIME

webMethods Integration Server Built-In Services Reference Version 9.6

522

Odd Header
MIME Folder

pub.mime:createMimeData
WmPublic. Creates a MIME object.
If no input parameter is passed to this service, the service creates an empty MIME object.
Otherwise, the service creates a MIME object containing the elements (header elds and
content) from the MIME message in input .
If you are building a MIME message, you use this service to create an empty
MIME object. You populate the empty MIME object with header elds and content,
and then pass it to pub.mime:getEnvelopeStream, which produces the nished MIME
message.
If you are extracting data from a MIME message, you use this service to parse the
original MIME message into a MIME object so that you can extract its header elds
and content using other webMethods services.
Input Parameters
input

java.io.InputStream Optional. MIME entity you want to parse. If input

is not provided, createMimeData creates an empty MIME object.

mimeHeader

Document Optional. Species header elds that you want to add

to the MIME object. Key names represent the names of the header
elds. The values of the keys represent the values of the header
elds.
Note: This parameter is ignored when input is passed to this service.
For example, if you wanted to add the following header elds:
X-Doctype: RFQ
X-Severity: 10

You would set mimeHeader as follows:

Key

Value

X-Doctype

RFQ

X-Severity

10

Be aware that the following MIME headers are automatically

inserted by pub.mime:getEnvelopeStream when it generates the MIME
message:
Message-ID
MIME-Version

webMethods Integration Server Built-In Services Reference Version 9.6

523

Even Header
MIME Folder

If you set these values in mimeHeader , pub.mime:getEnvelopeStream will

overwrite them at run time.
subType

String Optional. String that species the subtype portion of the

Content Type header, when the message is a multipart message and
\you want something other than the default value of mixed. For
example, if you want the Content Type header to be multipart/
related in the resulting message, set subType to related.
subType is ignored if the resulting message is not a multipart
message.

decodeHeaders

String Optional. Species how the MIME header is to be decoded.

Set to:
" "(empty String) to decode headers based on the value of the

global wa property wa.server.mime.decodeHeaders. This is the

default.
NONE to specify that the MIME header or body part headers do not

need decoding.

ONLY_MIME_HEADER to decode the MIME header only.

ONLY_BODY_PART_HEADERS to decode the body part headers only.
BOTH to decode the MIME header and the body part headers.

Output Parameters
mimeData

Document MIME object. If input was passed to createMimeData,

mimeData will contain the parsed MIME message. If input was not
passed to createMimeData, mimeData will be empty.

encrypted

String Conditional. Indicates whether input was an encrypted

message. This parameter is not present when the service creates a
new, empty MIME object. A value of:
true indicates that the message is encrypted (the original message

stream is in stream ).

false indicates that the message is not encrypted.

signed

String Conditional. Flag whose value indicates whether input was

a signed message. This parameter is not present when the service
creates a new, empty MIME object. A value of:
true indicates that the message is signed (the original message

stream is in stream ).

webMethods Integration Server Built-In Services Reference Version 9.6

524

Odd Header
MIME Folder

false indicates that the message is not signed.

certsOnly

String Conditional. Flag whose value indicates whether input

contained only digital certicates. (This type of message can be
produced by the pub.smime:createCertsOnlyData service and allows
digital certicates to be transported via the network as a MIME
message.) This parameter is not present when the service creates a
new, empty MIME object. A value of:
true indicates that the message contains only certicates.
false indicates that the message contains a regular payload.

stream

java.io.InputStream Conditional. InputStream containing the original

MIME message from input . This parameter is present only when
input is an S/MIME message.

Usage Notes
All of the other MIME services operate on the mimeData IData object produced by this
service. They do not operate directly on MIME message streams.
Important: You can examine the contents of mimeData during testing and debugging.
However, because the internal structure of mimeData is subject to change without
notice, do not explicitly set or map data to/from these elements in your service. To
manipulate or access the contents of mimeData , use only the MIME services that
Integration Server provides.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:addMimeHeader
pub.mime:addBodyPart
pub.mime:getMimeHeader
pub.mime:getBodyPartContent
pub.mime:getEnvelopeStream
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:build_SimpleMIME
samples.mime:build_MultipartMIME
samples.mime:extract_SimpleMIME

webMethods Integration Server Built-In Services Reference Version 9.6

525

Even Header
MIME Folder

samples.mime:extract_MultipartMIME

pub.mime:getBodyPartContent
WmPublic. Retrieves the content (payload) from the specied MIME object.
You use this service for both single-part and multi-part messages.
To retrieve content from a multi-part message, you set the index (to select the part by
index number) or contentID (to select the part by contentID value) parameter to specify
the body part whose content you want to retrieve. To get the content from a single-part
message, you omit the index and contentID parameters or set index to 0.
Input Parameters
mimeData

Document MIME object whose content you want to retrieve.

(This IData object is produced by pub.mime:createMimeData.)

index

String Optional. Index number of the body part whose content

you want to retrieve (if you want to retrieve the content from a
specic body part). The rst body part is index number zero.
Note: If contentID is specied, index is ignored.

contentID

String Optional. Value of the Content-ID header eld of the

body part whose content you want to retrieve (if you want to
retrieve the payload from a specic body part).

Output Parameters
content

IData The payload of the specied body part.

encrypted

String Flag whose value indicates whether content is an

encrypted MIME message. A value of:
true indicates that content is an encrypted message.
false indicates that content is not an encrypted message.

signed

String Flag indicating whether content is a signed MIME

message. A value of:
true indicates that content is a signed MIME message.
false indicates that content is not a signed MIME message.

webMethods Integration Server Built-In Services Reference Version 9.6

526

Odd Header
MIME Folder

certsOnly

String Flag whose value indicates whether content is a certsonly MIME message. A value of:
true indicates that content is a certs-only message.
false indicates that content is not a certs-only message.

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
If you omit index or contentID when retrieving content from a multi-part message,
getBodyPartContent returns the payload from the rst body part. If you use index or
contentID to select a body part that does not exist in mimeData , content will be null.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:addBodyPart
pub.mime:getBodyPartHeader
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:extract_SimpleMIME
samples.mime:extract_MultipartMIME

pub.mime:getBodyPartHeader
WmPublic. Returns the list of header elds for the specied body part.
Input Parameters
mimeData

Document MIME object whose message headers you

want to retrieve. (This IData object is produced by
pub.mime:createMimeData)

index

String Optional. Index number of the body part whose header

elds you want to retrieve. The rst body part is index zero.
Note: If contentID is specied, index is ignored.

webMethods Integration Server Built-In Services Reference Version 9.6

527

Even Header
MIME Folder

contentID

String Optional. Value of the Content-ID header eld of the

body part whose header elds you want to retrieve.

decodeHeaders

String Conditional. Flag whose value indicates whether to

decode encoded headers in the MIME object. Set to:
true to indicate that the headers should be decoded.
false to indicate that the headers should not be decoded.

This is the default.

Output Parameters
mimeHeader

Document IData object containing the message headers. Key

names represent the names of the header elds. The value of a
key represents the value of that header eld.
For example, if the original message contained the following
message header elds:
Content-Type: text/xml
X-Doctype: RFQ
X-Severity: 0

get Body Part Header would return the following IData object:
Key

Value

Content-Type

text/xml

X-Doctype

RFQ

X-Severity

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
If you omit index or contentID , getBodyPartHeader returns the message headers from the
rst body part. If you use index or contentID to select a body part that does not exist in
mimeData , content will be null.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:addBodyPart
webMethods Integration Server Built-In Services Reference Version 9.6

528

Odd Header
MIME Folder

pub.mime:getMimeHeader

pub.mime:getContentType
WmPublic. Returns the value of the Content-Type message header from the specied
MIME object.
Input Parameters
mimeData

Document MIME object whose Content-Type you

want to discover. (This IData object is produced by
pub.mime:createMimeData.

Output Parameters
contentType

String Value of the MIME object's Content-Type header

eld. Note that this service returns only the media type and
subtype portion of this header eld's value. It does not return
any parameters the value may include. For example, if the
message's Content-Type header were:
Content-Type: text/plain;charset=UTF8

contentType would contain:

text/plain

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:getSubContentType
pub.mime:getPrimaryContentType
pub.mime:getMimeHeader
pub.mime:getBodyPartHeader

pub.mime:getEnvelopeStream
WmPublic. Generates an InputStream representation of a MIME message from a
specied MIME object.

webMethods Integration Server Built-In Services Reference Version 9.6

529

Even Header
MIME Folder

Input Parameters
mimeData

Document MIME object from which you want to generate

the MIME message. (This IData object is produced by
pub.mime:createMimeData.)

index

String Optional. Index number of the body part for which you
want to generate the MIME message (if you want to generate
the message from a specic body part). The rst body part is
index number zero.

contentID

String Optional. Value of the Content-ID header eld of

the body part from which you want to generate the MIME
message (if you want to generate the message from a specic
body part).
Note: If index is specied, contentID is ignored.

suppressHeaders

String List Optional. Names of header elds that are to be

omied from message. You can use this option to exclude
header elds that getEnvelopeStream generates by default, such
as Content-Type and content-encoding.

createMultipart

String Optional. Species whether a multipart message is to be

created, even if mimeData contains only one body part. Set to:
yes to create a multipart message (Content-Type message

header is set to "multipart/mixed").

no to create a message based on the number of body parts in

mimeData . This is the default.

If the message contains only one body part, Content-Type

is set according to the contenype seing specied when
that body part was added to mimeData .
If the message contains multiple body parts, ContentType is automatically set to "multipart/mixed."
Output Parameters
envStream

java.io.InputStream The MIME message as an InputStream.

webMethods Integration Server Built-In Services Reference Version 9.6

530

Odd Header
MIME Folder

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
If you omit index or contentID , getEnvelopeStream generates the MIME message from the
entire contents of the mimeData . If you use index or contentID to select a body part that
does not exist in mimeData , content will be null.
getEnvelopeStream automatically inserts the MIME-Version and Message-ID message
headers into the MIME message it puts into envStream .
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:addBodyPart
pub.mime:addMimeHeader
Examples
For examples of how to use this service, see the following services in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:build_SimpleMIME
samples.mime:build_MultipartMIME

pub.mime:getMimeHeader
WmPublic. Returns the list of message headers from a specied MIME object.
Input Parameters
mimeData

Document MIME object whose message headers you

want to retrieve. (This IData object is produced by
pub.mime:createMimeData.)

Output Parameters
mimeHeader

Document Conditional. An IData object containing the message

headers. Key names represent the names of the header elds. The
value of a key represents the value of the header elds.

webMethods Integration Server Built-In Services Reference Version 9.6

531

Even Header
MIME Folder

For example, if the original message contained the following

message header elds:
Message-ID: <002e01c0f150$6f33010a@sgx.com>
From: "Purch01@GSX.com" <Purch01@GSX.com>To:
<EXPEst@exprint.com>
MIME-Version: 1.0
Content-Type: text/xml
X-Doctype: RFQ
X-Severity: 0

getMimeHeader would return the following:

Key

Value

Message-ID

<002e01c0f150$6f33010a@sgx.com>

From

"Purch01@GSX.com" <Purch01@GSX.com>

To

<EXPEst@exprint.com>

MIME-Version

1.0

Content-Type

text/xml

X-Doctype

RFQ

X-Severity

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:addMimeHeader
pub.mime:getBodyPartHeader

pub.mime:getNumParts
WmPublic. Returns the number of body parts in the specied MIME object.

webMethods Integration Server Built-In Services Reference Version 9.6

532

Odd Header
MIME Folder

Input Parameters
mimeData

Document MIME object whose parts you want to count. (This

IData object is produced by pub.mime:createMimeData.)

Output Parameters
numParts

String The number of body parts in the MIME object.

Usage Notes
This service operates on the MIME object (mimeData ) produced by createMimeData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:getBodyPartContent
pub.mime:addBodyPart
Examples
For examples of how to use this service, see the following service in the certied
samples area of the Knowledge Center on the Empower Product Support Websitehps://
empower.softwareag.com.
samples.mime:extract_MultipartMIME

pub.mime:getPrimaryContentType
WmPublic. Returns the top-level portion of a MIME object's Content-Type value.
Input Parameters
mimeData

Document MIME object whose Content-Type you

want to discover. (This IData object is produced by
pub.mime:createMimeData.)

Output Parameters
primContentType

String Message's top-level Content-Type. For example, if the

message's Content-Type header were:

webMethods Integration Server Built-In Services Reference Version 9.6

533

Even Header
MIME Folder

Content-Type: multipart/mixed

primContentType would contain:

multipart

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.mime:createMimeData
pub.mime:getContentType
pub.mime:addMimeHeader
pub.mime:getBodyPartHeader

pub.mime:getSubContentType
WmPublic. Returns the sub-type portion of a MIME object's Content-Type value.
Input Parameters
mimeData

Document MIME object whose sub-type you want to discover.

(This IData object is produced by pub.mime:createMimeData.)

Output Parameters
subContentType

String Message's sub-type. For example, if the message's

Content-Type header were:
Content-Type: multipart/mixed

subContentType would contain:

mixed

Usage Notes
This service operates on the MIME object (mimeData ) produced by
pub.mime:createMimeData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

534

Odd Header
MIME Folder

See Also
pub.mime:createMimeData
pub.mime:getContentType
pub.mime:addMimeHeader
pub.mime:getBodyPartHeader

pub.mime:mergeHeaderAndBody
WmPublic. Concatenates the contents of the header and body returned by the
pub.client:http service.
You can use this service to reassemble the message into its original form so that it can be
used as input to the pub.mime:createMimeData service (or any other service that requires the
entire hp response as an InputStream).
Input Parameters
headerLines

Document IData object containing the message headers

returned by pub.client:http. (The message headers are returned in
the lines document inside the header output parameter that is
produced by pub.client:http.)

body

Document IData object containing the body of the message

returned by pub.client:http. This document must contain the
body of the message in one of the following keys:
Key

Description

bytes

byte[ ] Optional. Body of the message (if

pub.client:http returned the body as a byte[ ]).

stream

java.io.InputStream Optional. The body of the

message (if pub.client:http returned the body as an
InputStream).

Output Parameters
stream

java.io.InputStream InputStream containing the reassembled tap

message.

webMethods Integration Server Built-In Services Reference Version 9.6

535

Even Header
MIME Folder

Usage Notes
Use this service to merge the results produced by pub.client:http to get the original MIME
message.
See Also
pub.client:http
pub.mime:createMimeData

webMethods Integration Server Built-In Services Reference Version 9.6

536

Odd Header
OAuth Folder

20 OAuth Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

538

537

Even Header
OAuth Folder

Use the elements in the oauth folder to authorize a client application to access data on
Integration Server using the OAuth 2.0 Authorization Framework.
Client applications use these services to interact with Integration Server when
Integration Server is congured to act as the OAuth authorization server. In this chapter,
authorization server refers to the Integration Server that acts as the authorization server.
For information about conguring Integration Server as the OAuth authorization server,
see webMethods Integration Server Administrators Guide.
Note: Before using these services, you must have already registered the client with the
authorization server and received a client identier. You will use this information to
congure the services in this folder. For information about registering a client, see
webMethods Integration Server Administrators Guide.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.oauth:authorize

Initiates an authorization request from a client

application to the authorization server.

pub.oauth:getAccessToken

Requests an access token from the authorization

server.

pub.oauth:refreshAccessToken

Requests a fresh token from the authorization server.

pub.oauth:authorize
Initiates an authorization request from a client application to the authorization server.
Input Parameters
response_type

String The grant type preferred by the client. This

parameter informs the authorization server how to
respond to the client. Set to:
code for the authorization code grant. When set to code,
the response from authorization server must include an
OAuth authentication code the client can exchange for an
access token.

webMethods Integration Server Built-In Services Reference Version 9.6

538

Odd Header
OAuth Folder

token for an implicit grant type. When set to token, the

response from authorization server includes an OAuth

access token for the client.

For more information about grant types, see "Usage Notes"

on page 539.
client_id

String The client identier generated by the authorization

server when the client application is registered. The
client_id is used to authenticate the client to the
authorization server.

redirect_uri

String Optional. The URI that the authorization server will

use to redirect the client when the client is authorized.
This parameter is required if the client is registered with
more than one redirect URI. The value for redirect_uri must
match one of the client's registered redirect URIs.

scope

String Optional. The name of the scope associated with the

client. The scope denes the level of access requested by
the client.
Specify the name of one or more scopes. Use a space to
separate the name of the scopes. For example:
scope1 scope2 scope3

The scopes you specify must already exist on the

authorization server. For information about creating a
scope, see webMethods Integration Server Administrators
Guide.
state

String Optional. A unique string used to maintain the state

between the request and callback. When the authorization
server redirects the user to the redirect_uri , the value
for state will be included in the response. Software AG
recommends using this parameter to protect against crosssite request forgery (CSRF) aacks.

Output Parameters
None.
Usage Notes
This service must be invoked using HTTPS unless the Require HTTPS seing on the
Security > OAuth > Edit OAuth Global Settings page is disabled.

webMethods Integration Server Built-In Services Reference Version 9.6

539

Even Header
OAuth Folder

When you register a client, you must consider the grant type the client should use to
obtain an access token. Integration Server supports the following grant types:
Authorization code. Requires the client to authenticate to the authorization server
before obtaining an access token. The authentication code supplied by the
authorization server is included in the redirection URI. The client can refresh an
expired token. To implement an authorization code grant, set the response_type to
code.
Implicit. Less secure than the authorization code grant. It does not require the client
to authenticate to the authorization server. The authentication server includes the
access token in the redirection URI. The client cannot refresh an expired token. To
implement an implicit grant, set the response_type to token.
Authentication code is not persisted in the cache. If Integration Server is restarted after
the authorization code is issued but before the access token is requested, Integration
Server will reject the request for the access token.

pub.oauth:getAccessToken
Requests an access token from the authorization server.
The authorization server validates the request and generates an access token and a
refresh token (if one is requested). The tokens, along with the client identier, token
expiration interval, and scope are stored in the authorization server's cache.
Input Parameters
grant_type

String Species the type of grant ow required by the client.

Since this service is for authorization code grant ows, you
must specify authorization_code.

client_id

String The client identier generated by the authorization

server when the client application is registered. The
client_id is used to authenticate the client to the
authorization server.
Public clients must provide a value for client_id .
Condential clients do not need to provide a value for
this parameter because they are required to use HTTP
authentication to identify themselves.

code

String The OAuth authorization code received from the

authorization server.

webMethods Integration Server Built-In Services Reference Version 9.6

540

Odd Header
OAuth Folder

redirect_uri

String The URI the authorization server will use to redirect

the client when the client is authorized.

Output Parameters
access_token

String The access token issued by the authorization server.

token_type

String The type of access token issued by the authorization

server. The value is Bearer.

expires_in

String The number of seconds for which the access token is

valid.

refresh_token

String Optional. The refresh token issued by the

authorization server. You can use this token to obtain new
access tokens using the same authorization grant.
If the client is registered with a refresh limit of 0, no refresh
token is issued.

Usage Notes
This service is used with authentication code grant ows only.
This service must be invoked using HTTPS unless the Require HTTPS seing on the
Security > OAuth > Edit OAuth Global Settings page is disabled.
Clients must invoke this service via an HTTP POST request.
Condential clients must authenticate requests by supplying their credentials in the
HTTP Authorization header.
Authentication code is not persisted in the cache. If Integration Server is restarted after
the authorization code is issued but before the access token is requested, Integration
Server will reject the request for the access token.
When Integration Server acts as the authorization server, the token_type output
parameter is always Bearer. The authorization server retains the information about the
bearer tokens it issues, including the user information. When the client presents a bearer
token to the resource server, the resource server checks with the authorization server to
see whether the user is allowed to access the requested folders and services.
The tokens, authorization codes, and client information are stored in the authorization
server's caches. By default, these caches maintain up to 1000 elements in memory
and 10000 elements on disk. If the cache size is exceeded, OAuth performance can be
aected on Integration Server and can lead to errors if the disk runs out of space. If you
anticipate that your authorization server's cache will exceed the default size, you should
increase the Maximum Elements In Memory, Maximum Elements On Disk, or Maximum OffHeap seings for Integration Server. For information about changing these seings, see

webMethods Integration Server Built-In Services Reference Version 9.6

541

Even Header
OAuth Folder

webMethods Integration Server Administrators Guide. If the cache is distributed, see hp://
ehcache.org/documentation/2.6 for additional considerations when sizing distributed
caches.

pub.oauth:refreshAccessToken
Requests a refresh token from the authorization server. If the authorization server issued
a refresh token to the client with the initial request, the client can use this service to
submit a token refresh request when that initial refresh token expires.
Input Parameters
grant_type

String Specify the type of grant ow required by the client.

For refresh tokens, you must specify refresh_token.

refresh_token

String Refresh token issued to the client by the

authentication server.

scope

String Optional. Specify the name of one or more scopes

required by the client. Use a space to separate multiple
scopes.
The value for scope must match or be a subset of the
value you provided for the pub.oauth:authorize and
pub.oauth:getAccessToken services.
The scope of the refresh token can be smaller than the
original request. It cannot contain any scope tokens that
were not in the original request.

Output Parameters
access_token

String The access token issued by the authorization server.

token_type

String The type of access token issued by the authorization

server. The value is Bearer.

expires_in

String The number of seconds for which the access token is

valid.

refresh_token

String The refresh token issued by the authorization server.

You can use this token to obtain new access tokens using
the same authorization grant.

webMethods Integration Server Built-In Services Reference Version 9.6

542

Odd Header
OAuth Folder

scope

String Conditional. The name of the scopes requested by the

client.

Usage Notes
This service is used with authorization grant ows only.
This service must be invoked using HTTPS unless the Require HTTPS seing on the
Security > OAuth > Edit OAuth Global Settings page is disabled.
Clients must invoke this service via an HTTP POST request.
Condential clients must authenticate requests by supplying their credentials in the
HTTP Authorization header.
When Integration Server acts as the authorization server, the token_type output
parameter is always Bearer. The authorization server retains the information about the
bearer tokens it issues, including the user information. When the client presents a bearer
token to the resource server, the resource server checks with the authorization server to
see whether the user is allowed to access the requested folders and services.

webMethods Integration Server Built-In Services Reference Version 9.6

543

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

544

Odd Header
Packages Folder

21 Packages Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

546

545

Even Header
Packages Folder

You use the elements in the packages folder to install, load, and/or alter the status of a
package on the Integration Server.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.packages:activatePackage

WmPublic. Activates (makes available to

clients) an inactive package.

pub.packages:backupPackage

WmPublic. Creates a backup copy of a

specied package.

pub.packages:disablePackage

WmPublic. Disables a package, thus

prohibiting access to the services in the
package.

pub.packages:enablePackage

WmPublic. Enables a package that has been

disabled.

pub.packages:installPackage

WmPublic. Installs a package that has been

published to this server.

pub.packages:recoverPackage

WmPublic. Recovers a package that exists in

the server's salvage directory.

pub.packages:reloadPackage

WmPublic. Loads a new copy of the package

into memory from disk.

pub.packages:activatePackage
WmPublic. Activates (makes available to clients) an inactive package.
You use this service to activate a package that was not activated when it was initially
installed or recovered.
Note: This service activates packages from an inactive state (that is, packages that are
installed on the server but are not registered in the active-package list). To enable a
package that is in a disabled state, you use pub.packages:enablePackage.

webMethods Integration Server Built-In Services Reference Version 9.6

546

Odd Header
Packages Folder

Input Parameters
package

String Name of the package that you want to activate. Package

names are case sensitive.

Output Parameters
message

String Message from server. (This is the same message that

you receive when you activate a package with the Integration
Server Administrator.)

Usage Notes
This service will throw an exception if the package specied in package does not exist or
cannot otherwise be activated.
When a package is activated, it is loaded into memory in an enabled state (that is,
activatePackage automatically activates and enables the package.) You do not need to
explicitly enable it with pub.packages:enablePackage.
See Also
pub.packages:enablePackage
pub.packages:installPackage
pub.packages:recoverPackage

pub.packages:backupPackage
WmPublic. Creates a backup copy of a specied package.
Input Parameters
packageName

String Name of the package to back up.

Output Parameters
None.
Usage Notes
The service creates the backup in a le named packageName .zip, where packageName is
the name of the original package installed in Integration Server. The packageName .zip is
placed in the following directory:
Integration Server_directory\instances\instance_name \replicate\inbound

webMethods Integration Server Built-In Services Reference Version 9.6

547

Even Header
Packages Folder

If a package with the same name as the le produced by this service already exists in the
Integration Server_directory\instances\instance_name \replicate\inbound directory, the
service overwrites the existing .zip le with the backup copy that the service creates.
The backed up package is an exact copy of the specied package. Package metadata,
such as creation timestamp, will be the same in the backup as in the original package.
This is unlike package replication or package archiving in which the creation timestamp
reects the time the package was replicated or archived.

pub.packages:disablePackage
WmPublic. Disables a package, thus prohibiting access to the services in the package.
Input Parameters
package

String Name of the package that you want to disable. Package

names are case sensitive.

Output Parameters
message

String Message from server. (This is the same message that

you receive when you disable a package with the Integration
Server Administrator.)

Usage Notes
When a package is disabled, the services in the package are no longer available to the
clients. To re-enable a package that has been disabled, use pub.packages:enablePackage.
Important: Never disable the WmRoot package. Doing so would disable the server.
Be aware that if you disable a package while services in the package are being executed,
those services will most likely fail. disablePackage does not wait for in-progress services to
nish before disabling a package.
This service will throw an exception if the package specied in package does not exist or
cannot otherwise be disabled.
See Also
pub.packages:enablePackage

webMethods Integration Server Built-In Services Reference Version 9.6

548

Odd Header
Packages Folder

pub.packages:enablePackage
WmPublic. Enables a package that has been disabled.
Note: This service enables a package that is in a disabled state (that is, a package
that has been disabled through the Integration Server Administrator or the
pub.packages:disablePackage service). To activate a package that is in an inactive state, you
use enablePackage.
Input Parameters
package

String Name of the package that you want to enable. Package

names are case sensitive.

Output Parameters
message

String Message from server. (This is the same message that you
receive when you enable a package with the Integration Server
Administrator.)

Usage Notes
When you enable a package, the package is reloaded into memory from disk.
This service will throw an exception if the package specied in package does not exist,
has not been activated, or cannot otherwise be enabled.
See Also
pub.packages:disablePackage
pub.packages:activatePackage
pub.packages:reloadPackage

pub.packages:installPackage
WmPublic. Installs a package that has been published to this server.
Input Parameters
packageFile

String Name of the distribution le that contains the package

that you want to install. This le must reside in the server's

webMethods Integration Server Built-In Services Reference Version 9.6

549

Even Header
Packages Folder

inbound directory (Integration Server_directory\instances

\instance_name \replicate\inbound).
When specifying packageFile ,
Do include the .zip extension in the le name.
Do not include the directory path.
For example: myPackageFileAug2001.zip
activateOnInstall

String Flag that species whether you want Integration Server

to automatically activate the package after it is installed. Set to:
yes to activate the package after installation and make it

immediately available to clients. This is the default.

no to install the package without activating it afterwards. If

you install a package in this mode, it will not be accessible

until it is explicitly activated through the Integration Server
Administrator or the pub.packages:activatePackage service.
archiveOnInstall

String Optional. Flag that species whether you want

Integration Server to archive the package automatically after it
is installed. Set to:
yes to archive the package after installation. If you choose to

archive the package automatically, Integration Server moves

the package from the Integration Server_directory\instances
\instance_name \replicate\inbound directory
to the Integration Server_directory\instances
\instance_name \replicate\archive directory. This is the
default.
no to install the package without archiving it.

Output Parameters
message

String Message from server. (This is the same message that is

displayed when you install a package with the Integration
Server Administrator.)

Usage Notes
If the installed package replaces an existing package on the server,
pub.packages:installPackage will automatically put a backup copy of the existing package in
Integration Server_directory\instances\instance_name \replicate\salvage before it installs
the new package.

webMethods Integration Server Built-In Services Reference Version 9.6

550

Odd Header
Packages Folder

This service will throw an exception if the le named in packageFile does not exist or
cannot otherwise be installed correctly.
See Also
pub.packages:activatePackage
pub.packages:recoverPackage

pub.packages:recoverPackage
WmPublic. Recovers a package that exists in the server's salvage directory.
The salvage directory (Integration Server_directory\instances\instance_name \replicate
\salvage) is where the server keeps packages that are deleted with the "safe delete"
option or replaced with newer installed versions.
Input Parameters
package

String Name of the package that you want to recover. Package

names are case sensitive.

activateOnRecover

String Flag that species whether you want the server to

automatically activate the package after it is recovered. Set to:
yes to activate the package after it is recovered and make it

immediately available to clients.

no to recover the package without activating it afterwards. If

you recover a package in this mode, it will not be accessible

until it is explicitly activated through the Integration Server
Administrator or the pub.packages:activatePackage service.
Output Parameters
message

String Message from server. (This is the same message that is

displayed when you recover a package with the Integration
Server Administrator.)

Usage Notes
You can only recover packages that exist in the server's salvage directory.
If you recover a package that is currently installed on the server, the package from the
salvage directory replaces the version that is currently installed. (Be aware that the server
does not retain a copy of the version that it replaces.)

webMethods Integration Server Built-In Services Reference Version 9.6

551

Even Header
Packages Folder

This service will throw an exception if the le named in package does not exist in the
server's salvage directory or cannot otherwise be recovered.
See Also
pub.packages:activatePackage

pub.packages:reloadPackage
WmPublic. Loads a new copy of the package into memory from disk.
If you make changes to the service in a package while the server is running, you must
use reloadPackage to put those changes into eect.
Input Parameters
package

String Name of the package that you want to reload. Package

names are case sensitive.

Output Parameters
message

String Message from server. (This is the same message that is

displayed when you reload a package with the Integration
Server Administrator.)

Usage Notes
Be aware that if you reload a package while services in the package are being executed,
those services will most likely fail. reloadPackage does not wait for in-progress services to
nish before reloading a package.
This service will throw an exception if the le named in package does not exist or cannot
otherwise be reloaded.

webMethods Integration Server Built-In Services Reference Version 9.6

552

Odd Header
PKI Folder

22 PKI Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

554

553

Even Header
PKI Folder

You use the elements in the pki folder to create and verify PKCS#7 signatures with PKI
proles. You also use elements in this folder to create and process S/MIME messages
using PKI proles.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.pki.pkcs7:sign

WmPKI. Creates a PKCS7 SignedData

object using a PKI prole.

pub.pki.pkcs7:verify

WmPKI. Processes a digital signature to

make sure that the provided data has not
been modied.

pub.pki.smime.createSignedAndEncryptedData

WmPKI. Digitally signs a MIME message

and then encrypts it.

pub.pki.smime.createSignedData

WmPKI. Digitally signs a MIME message

using a specied PKI prole.

pub.pki.smime:processEncryptedData

WmPKI. Decrypts an encrypted S/MIME

message using a specied PKI prole.

pub.pki.smime:processSignedData

WmPKI. Veries the signature from a

signed S/MIME entity using a specied
PKI prole, and then extracts the message
from the S/MIME entity.

pub.pki.pkcs7:sign
WmPKI. Creates a PKCS7 SignedData object using a PKI prole.
This service enables multiple entities to sign the specied data. Each signerInfo block
contained in the resulting signature contains two authenticated aributes: the content
type and a timestamp.
Note: This service is similar to pub.security.pkcs7:sign except that it uses a PKI prole to
create the PKCS7 SignedData object.

webMethods Integration Server Built-In Services Reference Version 9.6

554

Odd Header
PKI Folder

Input Parameters
signerInfo

Document List Information about a single signer of the signed

data object.
Note: This service accepts only one signerInfo .
Key

Description

proleAlias

String PKI prole alias used to sign

the data. This service retrieves the
key from the prole to perform the
signing operation and includes the
associated public and CA certicates in
the signature that it generates.

hashAlgorithm

String Optional. The algorithm to use

when computing the digest of the
provided data. Specify:
MD5
SHA-1 (the default)
SHA-256
SHA-384
SHA-512

data

byte[ ] Data to be digitally signed.

detachedSignature

String Flag specifying whether to generate a detached

signature. A detached signature does not include the data that
was signed. Set to:
true to generate a detached signature.
false to generate an implicit signature (one that includes the

signed data). This is the default.

Output Parameters
signature

byte[ ] Signature generated from the supplied data. This is

a DER-encoded representation of the SignedData object as
specied in PKCS#7.

webMethods Integration Server Built-In Services Reference Version 9.6

555

Even Header
PKI Folder

pub.pki.pkcs7:verify
WmPKI. Processes a digital signature to make sure that the provided data has not been
modied.
Note: This service is similar to pub.security.pkcs7:verify except that it uses a PKI prole to
obtain the certicate against which to verify the signer's signature.
Input Parameters
proleAlias

String Name of the PKI prole to be used for certicate

verication.

signature

byte[ ] Signature to use to determine whether the signed data is

intact (a DER-encoded representation of the SignedData object
as specied in PKCS#7). If you are processing a detached
signature, pass the signature in signature . If you are processing
an implicit signature, pass the entire signed entity in signature .

data

byte[ ] Optional. The data that was signed. If you are

processing an implicitly signed message, you do not need to
supply data because both the data and the signature reside in
signature .

detachedSignature

String Flag indicating whether the message has a detached

signature. Set to:
true to indicate that the message has a detached signature.
false to indicate that the message has an implicit signature.

This is the default.

signerCertChain

byte[ ][ ] Optional. Certicate chains of the parties that signed

the message.
Note: If the signers included the certicate chain with the digital
signature, you do not need to supply signerCertChain .

Output Parameters
content

byte[ ] Conditional. The data (for example, the document that

was originally signed) extracted from an implicit signature. If
you are verifying a detached signature, content is not returned.

webMethods Integration Server Built-In Services Reference Version 9.6

556

Odd Header
PKI Folder

Note: The extracted data is returned in content even if signature

verication fails.
signerInfo

Document List Information about the signers. Each document

in the list provides the following information about a single
signer:
Key

Description

certChain

java.security.cert.X509Certificate[ ] Certicate
chain of the signer. The chain will appear in
hierarchical order, starting with the signer's
X.509 certicate in element 0.

timeStamp

java.util.Date Time at which the signer signed

the data.

trusted

String Flag indicating whether the certicate

chain presented by the signer is trusted. A
value of:
true indicates that the chain is trusted.
false indicates that the chain is not trusted.

status

errorMessage

String Code indicating whether the signatures

were successfully veried. If successful,
status contains verified. If the signatures
were not successfully veried, status contains
an error message.

String Conditional. If the signatures were not successfully

veried, this parameter contains the text "Invalid signer
certificate file information."

pub.pki.smime.createSignedAndEncryptedData
WmPKI. Digitally signs a MIME message and then encrypts it.
Note: This service is similar to pub.smime:createSignedAndEncryptedData and
pub.smime.keystore:createSignedAndEncryptedData except that a PKI prole is used to provide
signing key and certicate information.

webMethods Integration Server Built-In Services Reference Version 9.6

557

Even Header
PKI Folder

Input Parameters
envStream

java.io.InputStream The MIME message that you want to

sign and encrypt (for example, the output produced by
pub.mime:getEnvelopeStream).

proleAlias

String PKI prole alias to use to sign the data. This service
retrieves the key from the prole to perform the signing
operation and includes the associated public and CA
certicates in the signature that it generates.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is to be generated. Set to:
true to generate an explicit (detached) signature. This is the

default.

false to generate an implicit signature.

recipientCerts

byte[ ][ ] X.509 certicates of the recipients for whom this

message will be encrypted. Each element in the list contains
the certicate for a single recipient, in the form of a byte array.
Note: For multiple recipients, this service creates a single
message that is encrypted for all recipients. It does not create a
separate message for each recipient.

encryptionAlg

String Optional. Code specifying the encryption algorithm to

use. Must be one of the following values:
TripleDES
DES
RC2

Default is TripleDES
keyLength

String Optional. Length of the encryption key for RC2

encryption. Must be one of the following values:
40
64
128

Default is 128. This parameter is ignored if encryptionAlg is

not RC2.
Output Parameters
SMimeEnvStream

java.io.InputStream Signed and encrypted MIME message.

webMethods Integration Server Built-In Services Reference Version 9.6

558

Odd Header
PKI Folder

pub.pki.smime.createSignedData
WmPKI. Digitally signs a MIME message using a specied PKI prole.
Note: This service is similar to pub.smime:createSignedData and
pub.smime.keystore:createSignedData except that a PKI prole supplies signing key and
certicate information.
Input Parameters
envStream

java.io.InputStream MIME message that you want to sign (for

example, the output produced by pub.mime:getEnvelopeStream).

proleAlias

String PKI prole alias to use to sign the message. This

service retrieves the key from the prole to perform the
signing operation and includes the associated public and CA
certicates in the signature that it generates.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is to be generated. Set to:
true to generate an explicit (detached) signature. This is the

default.

false to generate an implicit signature.

Output Parameters
SMimeEnvStream

java.io.InputStream Signed MIME message.

pub.pki.smime:processEncryptedData
WmPKI. Decrypts an encrypted S/MIME message using a specied PKI prole.
Note: This service is similar to pub.smime:processEncryptedData and
pub.smime.keystore:processEncryptedData except that a PKI prole supplies signing key and
certicate information.

webMethods Integration Server Built-In Services Reference Version 9.6

559

Even Header
PKI Folder

Input Parameters
SMimeEnvStream

java.io.InputStream The encrypted S/MIME entity (for example,

the output produced by pub.smime:createEncryptedData).

proleAlias

String PKI prole to use to decrypt the message. This service

retrieves the decryption key and public encryption certicate
from the prole to perform the decryption operation.

Output Parameters
mimeData

Document MIME object containing the decrypted MIME

message.

contentDigest

String Message digest of the encrypted content, base64encoded. (Some sites return this digest to the sender to
acknowledge their receipt of the message.)

encrypted

String Conditional. Flag indicating whether the decrypted

MIME entity is encrypted. A value of:
true indicates that the MIME entity is encrypted.
false indicates that the MIME entity is not encrypted.

signed

String Conditional. Flag indicating whether the decrypted

MIME entity is signed. A value of:
true indicates that the MIME entity is signed.
false indicates that the MIME entity is not signed.

certsOnly

String Conditional. Flag indicating whether the decrypted

MIME entity is a certs-only entity. A value of
true indicates that the MIME entity is a certs-only entity.
false indicates that the MIME entity is not a certs-only

entity.
stream

java.io.InputStream Conditional. The decrypted MIME entity.

This parameter is present only when the decrypted entity is an
S/MIME message.

webMethods Integration Server Built-In Services Reference Version 9.6

560

Odd Header
PKI Folder

pub.pki.smime:processSignedData
WmPKI. Veries the signature from a signed S/MIME entity using a specied PKI
prole, and then extracts the message from the S/MIME entity.
Note: This service is like pub.smime:processSignedData except that a PKI prole supplies the
certicates against which the signature is veried.
Input Parameters
SMimeEnvStream

java.io.InputStream Signed MIME entity (for example, the output

produced by "pub.pki.smime.createSignedData" on page
559).

proleAlias

String PKI prole to use for certicate validation.

signerCertChain

byte[ ][ ] Optional. Certicate chain of the party that signed

the message. Certicates must appear in hierarchical order,
starting with the signer's certicate in element 0.
The following shows how the elements of a complete chain
would appear for a certicate that was issued through two
intermediate CAs.
Element

Contents

Signer's certicate

Intermediary CA Certicate

Intermediary CA Certicate

Root CA Certicate

Note: If the signer included the certicate chain with the digital
signature, you do not need to supply signerCertChain .
Output Parameters
mimeData

Document MIME object containing the extracted MIME entity.

webMethods Integration Server Built-In Services Reference Version 9.6

561

Even Header
PKI Folder

contentDigest

String Message digest (base64-encoded) that processSignedData

recalculated.

signerCert

java.security.cert.X509Certificate Signer's X509 certicate.

encrypted

String Conditional. Flag indicating whether the extracted

MIME entity is encrypted. A value of:
true indicates that the MIME entity is encrypted.
false indicates that the MIME entity is not encrypted.

signed

String Conditional. Flag indicating whether the extracted

MIME entity is signed.
true indicates that the MIME entity is signed.
false indicates that the MIME entity is not signed.

certsOnly

String Conditional. Flag indicating whether the extracted

MIME entity is a certs-only entity.
true indicates that the MIME entity is a certs-only entity.
false indicates that the MIME entity is not a certs-only

entity.
stream

java.io.InputStream Conditional. Extracted MIME entity. This

parameter is present only when the decrypted entity is an S/
MIME message.

verify

String Flag indicating whether the signature was successfully

processed (that is, the signature was successfully veried with
the public key supplied by the PKI prole).
true indicates that signature processing was successful.
false indicates that signature processing failed. The

signature could not be veried because errorCode 1 or 4

occurred (see errorCode below).
trusted

String The signer is a trusted entity. For the signer to be trusted,

the signer's certicate or one of its root certicates should be
present in the trusted CA directory.
true indicates that the signer is a trusted entity.
false indicates that the signer is not a trusted entity.

webMethods Integration Server Built-In Services Reference Version 9.6

562

Odd Header
PKI Folder

errorCode

String Conditional. Number indicating what kind of error

occurred, if any, while processing the signature. See
errorMessage for possible values.
If no error occurred, errorCode is not returned.

errorMessage

String Conditional. Textual error message indicating what kind

of error occurred, if any, while processing the signature.
errorCode

errorMessage

Invalid signer certificate chain file

information.

Signature cannot be verified.

Expired certificate chain.

Error in certificate chain.

Untrusted certificate.

Usage Notes
If verify is false, the errorCode and errorMessage values will indicate the error that
caused the failure. Note that errorCode values 5 through 7 do not represent signatureverication failures, and therefore do not cause the verify ag to be set to false.
If the extracted entity is signed or encrypted, mimeData will be empty and the extracted
entity will reside in stream. You can check the state of the signed and encrypted output
variables to determine whether the extracted entity requires additional processing, then
pass stream to the processEncryptedData service as necessary.
See Also
pub.smime:processEncryptedData
pub.smime:createSignedData
pub.smime.keystore:createSignedData
pub.smime.keystore:processEncryptedData

webMethods Integration Server Built-In Services Reference Version 9.6

563

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

564

Odd Header
Publish Folder

23 Publish Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

566

565

Even Header
Publish Folder

You use the elements in the publish folder to publish messages to webMethods
Universal Messaging or webMethods Broker. Other Integration Servers subscribe to and
receive these messages using webMethods messaging triggers.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.publish:deliver

WmPublic. Delivers a document to a specic

destination.

pub.publish:deliverAndWait

WmPublic. Requests a reply document from a

specic client. The service waits for the reply or
indicates that the pub.publish:waitForReply service
should retrieve the reply later.

pub.publish:documentResolverSpec

WmPublic. Specication for the signature of a

service that determines whether a document's
status is New, Duplicate, or In Doubt.

pub.publish:envelope

WmPublic. Document type that denes the

content and structure of the envelope that
accompanies a published document.

pub.publish:getRedeliveryCount

WmPublic. Retrieves the redelivery count for a

document.

pub.publish:publish

WmPublic. Publishes a document locally or to the

messaging provider.

pub.publish:publishAndWait

WmPublic. Broadcasts a request for a document

from any client subscribed to a specic document
type. The service waits for the reply or indicates
that the pub.publish:waitForReply service should
retrieve the reply later.

pub.publish:reply

WmPublic. Delivers a reply document to the

requesting client.

pub.publish:syncToBroker

WmPublic. Synchronizes one or more publishable

document types with their associated denition

webMethods Integration Server Built-In Services Reference Version 9.6

566

Odd Header
Publish Folder

Element

Package and Description

on the messaging provider by pushing the
publishable document types to the provider.

pub.publish:waitForReply

WmPublic. Retrieves the reply for an

asynchronous request. If a reply is not available,
the Integration Server continues to wait for
the document until the time specied in the
waitTime parameter of the pub.publish:deliverAndWait
or pub.publish:publishAndWait service elapses.

pub.publish.notification:error

WmPublic. Publishable document type that

denes the document that Integration Server
generates and delivers when a trigger encounters
an error or exception condition during processing.

pub.publish:deliver
WmPublic. Delivers a document to a specic destination.
Note: The pub.publish:deliver service can be used to publish a document to webMethods
Broker only.
Input Parameters
documentTypeName

String Fully qualied name of the publishable document

type being delivered.
The publishable document type must be synchronized
with the associated Broker document type. If the
document types are not synchronized, publication fails.

document

Document Document (IData object) conforming to the

publishable document type in documentTypeName .

destId

String The client ID to which the document will be

delivered. You can specify the default client ID for an
Integration Server, or you can specify the client ID for
an individual trigger. If you specify an incorrect client
ID, the Integration Server delivers the document to the
Broker, but the Broker never delivers the document to
the intended recipient and no error is produced.

webMethods Integration Server Built-In Services Reference Version 9.6

567

Even Header
Publish Folder

delayUntilServiceSuccess

String Optional. Flag indicating whether the Integration

Server should publish the document when the
pub.publish:deliver service executes or after the toplevel service successfully completes. If the top-level
service fails, the Integration Server will not publish the
document.
Set to:
true to delay publishing until after the top-level service

executes successfully.

false to publish the document when the

pub.publish:deliver service executes. This is the default.

Output Parameters
None.
Usage Notes
You can use the pub.publish:deliver service to deliver a document to a client on the Broker.
You cannot use pub.publish:deliver with Universal Messaging.
To view a list of client IDs on the Broker, use the Broker user interface within My
webMethods or use Designer to test the publishable document type that you want to
deliver.
For more information about how the Integration Server and Broker deliver documents
and for information about building a service that delivers a document, see the PublishSubscribe Developers Guide.
If outbound client-side queuing is disabled (the wa.server.publish.useCSQ property is
set to "never"), Integration Server throws a ServiceException if the Broker is not available
when this service executes. Make sure to code your service to handle this situation.
See Also
pub.publish:publish
pub.publish:deliverAndWait
pub.publish:envelope

pub.publish:deliverAndWait
WmPublic. Requests a reply document from a specic client. The service waits for the
reply or indicates that the pub.publish:waitForReply service should retrieve the reply later.
Note: The pub.publish:deliverAndWait can be used to publish a document to webMethods
Broker only.

webMethods Integration Server Built-In Services Reference Version 9.6

568

Odd Header
Publish Folder

Input Parameters
documentTypeName

String Fully qualied name of the publishable document type

being delivered.
Note: The publishable document type must be synchronized
with the associated Broker document type. If the document
types are not synchronized, publication fails.

document

Document Document (IData object) conforming to the

publishable document type in documentTypeName .

receiveDocumentType
Name

String Optional. Fully qualied name of the publishable

document type expected as a reply. If no value is specied,
the service uses the rst reply document of any type it
receives, as long as the value of tag in the envelope of
the reply document matches the tag in the envelope of
the published document. All other reply documents are
discarded.

destId

String The client ID to which the document will be delivered.

You can specify the default client ID for an Integration Server,
or you can specify the client ID for an individual trigger.
If you specify an incorrect client ID, the Integration Server
delivers the document to the webMethods Broker, but the
webMethods Broker never delivers the document to the
intended recipient and no error is produced.

waitTime

String Optional. Species the time to wait (in milliseconds)

for the response to arrive. If no value is specied, the service
waits indenitely until it receives a reply.

async

String Optional. Flag specifying whether this is an

asynchronous or synchronous request/reply. Set to:
true to indicate that this is an asynchronous request/reply.

After publishing the document, the Integration Server

executes the next step in the ow service immediately.
The Integration Server does not wait for a reply before
continuing service execution.

Note: To retrieve the reply to an asynchronous request,

invoke the pub.publish:waitForReply service.
false to indicate that this is a synchronous request/reply.

After publishing the document, the Integration Server waits

webMethods Integration Server Built-In Services Reference Version 9.6

569

Even Header
Publish Folder

for a reply before executing the next step in the ow service.

This is the default.
Output Parameters
receivedDocument

Document A Document (IData object) received as reply.

Important: Integration Server treats all reply documents as
volatile documents. If the Integration Server shuts down before
processing the reply document, the reply document is lost.
String Conditional. A unique identier for a deliver request.
The Integration Server uses the tag value to match the
requesting document with its corresponding reply document.

tag

The service produces a tag output value only when the async
eld is set to true. The tag value is required input when using
the pub.publish:waitForReply service to retrieve the reply.
Note: The tag output value is the same value that the Integration
Server places in the tag eld of the request document's envelope.
Usage Notes
You can use the pub.publish:deliverAndWait service to publish a document to the Broker. You
cannot use pub.publish:deliverAndWait with Universal Messaging
You can use the pub.publish:deliverAndWait service to initiate and continue a private
conversation between two webMethods Broker clients. This is a variation of the request/
reply model. One client executes a service that delivers a document to a specic client.
This document requests information from the receiving client.
In a synchronous request/reply, the delivering service stops executing while it
waits for a response. When the service receives a reply document from the specied
client, the servers resumes executing. If the waitTime elapses before the service
receives a reply, the Integration Server ends the request, and the service returns a
null document indicating that the request timed out. The Integration Server then
executes the next step in the ow service. If a reply document arrives after the ow
service resumes execution, the Integration Server rejects the document and creates
a journal log message stating that the document was rejected because there is no
service thread waiting for the document.
In an asynchronous request/reply, the delivering service continues executing
the steps in the service after publishing the document. To retrieve the reply,
the delivering service must invoke the pub.publish:waitForReply service. If the wait
time elapses before the pub.publish:waitForReply service receives a document, the
pub.publish:waitForReply service returns a null document indicating that the request
timed out.

webMethods Integration Server Built-In Services Reference Version 9.6

570

Odd Header
Publish Folder

A service that contains multiple asynchronous deliver requests allows the service to
deliver all the requests before collecting the replies. This approach can be more ecient
than delivering a request, waiting for a reply, and then delivering the next request.
If you create a service that contains multiple asynchronous requests, make sure
to link the tag output to another eld in the pipeline. Each asynchronous delivery
produces a tag eld in the pipeline. If the tag eld is not linked to another eld, the next
asynchronous delivery request (that is, the next execution of the pub.publish:deliverAndWait
service) will overwrite the rst tag value.
To view a list of client IDs on the webMethods Broker, use the webMethods Broker user
interface or use Designer to test the publishable document type that you want to deliver.
Use pub.publish:deliverAndWait if you need to know that a specic client successfully
received and processed the request document.
For more information about how to build a services that initiate synchronous or
asynchronous request/reply scenarios, see the Publish-Subscribe Developers Guide.
If outbound client-side queuing is disabled (the wa.server.publish.useCSQ property is
set to "never"), Integration Server throws a ServiceException if the webMethods Broker
is not available when this service executes. Make sure to code your service to handle this
situation.
See Also
pub.publish:waitForReply
pub.publish:publishAndWait
pub.publish:reply
pub.publish:envelope

pub.publish:documentResolverSpec
WmPublic. Specication for the signature of a service that determines whether a
document's status is New, Duplicate, or In Doubt.
Input Parameters
documentTypeName

String Fully qualied name of the document whose status is In

Doubt.

redeliveryCount

String Number of times the document has been redelivered to

the trigger queue on the Integration Server.

uuid

String Universally unique identier for the document. The

publishing application assigns the uuid to a document.

webMethods Integration Server Built-In Services Reference Version 9.6

571

Even Header
Publish Folder

document

Document The document (IData object) whose status needs to

be resolved. This document must conform to the publishable
document type specied in documentTypeName .

transport

String The transport (such as LOCAL or BROKER) used to

send the document to the Integration Server.

triggerName

String The name of the webMethods messaging trigger that

received the document whose status needs to be resolved.

Output Parameters
status

String Indicates the status of the document. The value of this

eld determines whether the Integration Server processes the
document, discards the document, or sends the document to
the audit log. The status eld must have one of the following
values.
NEW indicates that the document is new and has not been

processed by the trigger. Integration Server instructs the

trigger to process the document.

DUPLICATE indicates that the document is a duplicate of one

already processed by the trigger. Integration Server discards

the document and generates a journal log message.
IN_DOUBT indicates that the status of the document is still in

doubt. The document resolver service could not conclusively

determine whether the trigger already processed the
document. If the audit log is a database, the audit subsystem
logs the document and the Integration Server generates a
journal log message.
message

String Conditional. A user-specied string that indicates why

the document status is DUPLICATE or IN_DOUBT. Integration
Server writes the message to the journal log when the server
discards the document or routes it to the audit log.

Usage Notes
The pub.publish:documentResolverSpec must be used as the signature for any service used to
resolve the processing status of a document. For information about building a document
resolver service and enabling exactly once processing for a webMethods messaging
trigger, see the Publish-Subscribe Developers Guide.
Use the pub.jms:documentResolverSpec as the signature for a document resolver service used
to determine the status of a JMS message received by a JMS trigger.

webMethods Integration Server Built-In Services Reference Version 9.6

572

Odd Header
Publish Folder

See Also
pub.jms:documentResolverSpec

pub.publish:envelope
WmPublic. Document type that denes the content and structure of the envelope that
accompanies a published document.
The envelope records information such as the sender's address, the time the document
was sent, password and certicate information, and other useful information for routing
and control. Every publishable document type contains a document reference to this
document type.
Read/Write Parameters
You can set the following parameters within your service. Broker supports all of the
read/write parameters. However, webMethods Universal Messaging supports only
activation , businessContext , and priority . Universal Messaging ignores the values of any
other read/write parameters set in the document envelope and passes them through to
subscribers.
activation

String Optional. A unique identier that any messaging client

(including the Integration Server) assigns to all documents
published as a result of the one-time execution of the
integration solution. If a document does not have an activation
ID, the Integration Server assigns one when the document is
published.
If you are using a trigger to join documents published by
dierent services, you must explicitly set the activation ID of
the documents. The services that publish the documents must
assign the same activation ID to the documents.

appLastSeqn

java.lang.Integer Optional. This eld is provided for backward

compatibility.

appPassword

String Optional. The password of the user specied in

appUserName . If the resource that processes the document
requires authentication before it begins processing, specify the
password in this eld.

appSeqn

java.lang.Integer Optional. This eld is provided for backward

compatibility.

webMethods Integration Server Built-In Services Reference Version 9.6

573

Even Header
Publish Folder

appUserName

String Optional. The user name for logging into the application
that processes the document. Use the appPassword eld to
specify the password for this user name.

businessContext

String Optional. Used by the Integration Server to track

business process context and audit context across multiple
Integration Servers.
Important: The businessContext eld is reserved for internal use by
the Integration Server. Do not set or overwrite the value of the
businessContext eld.

controlLabel

java.lang.Short[ ] Optional. This eld is provided for backward

compatibility.

errorsTo

String Optional. The client ID to which the Integration Server

sends an error notication document if errors occur during
document processing by subscribers. If this parameter is not
set, error notications will be sent to the document publisher.
The errors document is an instance of pub.publish.notification:error.

errorRequestsTo

String Optional. This eld is provided for backward

compatibility.

locale

String Optional. Locale of the publishing client expressed as a

URN (Uniform Resource Name). Trigger services examine the
locale value to determine the locale to use when processing the
document. If the locale eld is empty, the locale of the current
Integration Server is used instead.

maxResults

java.lang.Integer Optional. This eld is provided for backward

compatibility.

priority

java.lang.Integer Optional. Indicates how quickly the document

should be published and processed. A value of 0 is the
lowest processing priority; a value of 9 indicates expedited
processing. Set a message priority in the document envelope
when publishing the document. The default priority is 4.

replyTo

String Optional. The client ID to which the replies to the

published document should be sent. If this parameter is not
set, replies will be sent to the document publisher as specied
in pubId .

webMethods Integration Server Built-In Services Reference Version 9.6

574

Odd Header
Publish Folder

runLevel

java.lang.Integer Optional. This eld is provided for backward

compatibility.

signature

byte[ ] Optional. A byte sequence that holds a digital signature.

Specify a digital signature if clients receiving this document
requires one.

signatureType

String Optional. The type of digital signature being used.

startResult

java.lang.Integer Optional. This eld is provided for backward

compatibility.

tag

java.lang.Integer Optional. Used with pub.publish:publishAndWait

and pub.publish:deliverAndWait to match a request document with
its corresponding reply document.
Important: The tag eld is reserved for internal use by the
Integration Server. Do not set or overwrite the value of the tag
eld in the envelope.

trackId

String Optional. A unique identier assigned to a published

document by the publishing client application. If no value is
specied, Integration Server populates this eld with the value
of the uuid eld.

transactionId

String Optional. This eld is provided for backwards

compatibility.

transformState

String Optional. An indication of a document's current state,

set by a publishing client application that transforms data.
For example, a client could publish a document with a
transformState value of "USEnglish" and a receiving client
could translate the document into French and publish it with a
transformState value of "French."

Read-only Parameters
webMethods Universal Messaging, webMethods Broker, or Integration Server set the
following parameters. You cannot set these parameters within your service, but you can
retrieve their values from published documents.
Note: Of the read-only parameters listed below, webMethods Universal Messaging
supports the uuid and recvTime parameters only.
age

java.lang.Integer Optional. The cumulative time, in seconds,

that the document spends on all webMethods Brokers. The

webMethods Integration Server Built-In Services Reference Version 9.6

575

Even Header
Publish Folder

webMethods Broker starts tracking the document age when

it receives the document from the publishing client. The
webMethods Broker stops tracking the document age when
the subscribing client removes the document from the client
queue. If the document is routed to successive webMethods
Brokers, age also includes the length of time the document
spends on the other webMethods Brokers.
connectionIntegrity

String Optional. An indication of whether the received

document passed over a link that is not secure. This eld
can have one of the following values:
< empty > indicates that at some point, the document
passed through a connection that was not encrypted.
U.S Export indicates that all the connections used
to transport the event had an encryption strength of
ENCRYPT_LEVEL_US_EXPORT or greater.
U.S. Domestic indicates that the event traveled
exclusively over connections with an encryption strength
of ENCRYPT_LEVEL_US_DOMESTIC.

destId

String Optional. The ID of the client to which the document

is being delivered. The publishing client sets the destID
when it publishes the document. For example, the
Integration Server uses the destID value specied in the
pub.publish:deliver service or the pub.publish:deliverAndWait service
to populate the destID value in the document envelope.

enqueueTime

java.util.Date Optional. The date and time that the

webMethods Broker placed the document into the client
queue.

logBroker

String Optional. The name of the webMethods Broker

that contains the document in its document log. The
webMethods Broker sets this parameter when webMethods
Broker-based document logging and the logging utility are
enabled.

logHost

String Optional. The host name and port number of the

webMethods Broker that contains the document in its
document log. The webMethods Broker sets this parameter
when webMethods Broker-based document logging and the
logging utility are enabled.

pubDistinguishedName

String Optional. The distinguished name of the publisher's

SSL certicate. The webMethods Broker sets this parameter
when the publisher has an SSL connection to the

webMethods Integration Server Built-In Services Reference Version 9.6

576

Odd Header
Publish Folder

webMethods Broker and clears this parameter when the

publisher has a non-SSL connection.
pubId

String Optional. The client ID of the document's publisher. If

the publishing client is connected to a dierent webMethods
Broker than the recipient, the webMethods Broker uses the
fully qualied client ID (that is, the webMethods Broker
prexes the client ID with the name of the publisher's
webMethods Broker). You can use the Integration Server
Administrator to view the client ID for an Integration
Server. You can use the webMethods Broker user interface
on My webMethods to view the client IDs for all clients
connected to a webMethods Broker.

pubNetAddr

byte[ ] Optional. The IP address and port number of the

document's publisher.

pubSeqn

java.lang.Long Optional. This eld is provided for backwards

compatibility.

pubLabel

java.lang.Short[ ] Optional. This eld is provided for

backwards compatibility.

recvTime

java.util.Date Optional. The date and time the document was

received by the messaging provider.

route

Document List Optional. Information about the webMethods

Brokers through which a document passed. When a
webMethods Broker receives a document, the webMethods
Broker sets the broker and recvTime keys. When the
webMethods Broker places the document in the queue for
the next webMethods Broker, the rst webMethods Broker
sets enqueueTime . The webMethods Broker only sets these
elds when document is forwarded from one webMethods
Broker to another. The webMethods Broker does not set
these elds when the publishing and receiving clients are
connected to the same webMethods Broker.
Key

Description

broker

String Optional. The name of the

webMethods Broker.

recvTime

java.util.Date Optional. The time the

webMethods Broker received the

webMethods Integration Server Built-In Services Reference Version 9.6

577

Even Header
Publish Folder

document from the publishing client

or another webMethods Broker.
enqueueTime

uuid

java.util.Date Optional. The time the

webMethods Broker placed the
document in the queue for the next
webMethods Broker.

String Optional. Universally unique identier for the

document. The Integration Server assigns the UUID when
it publishes the document. The receiving Integration Server
uses the UUID to detect duplicate documents.

Output Parameters
None.
Usage Notes
For more information about seing and using a document's envelope parameters, see
webMethods Broker Java Client API Reference, webMethods Broker Client C API Programmers
Guide, and Publish-Subscribe Developers Guide.
See Also
pub.publish:deliver
pub.publish:deliverAndWait
pub.publish:publish
pub.publish:publishAndWait
pub.publish:publishAndWait
pub.publish.notification:error

pub.publish:getRedeliveryCount
WmPublic. Retrieves the redelivery count for a document.
The redelivery count indicates the number of times the document has been redelivered
to the trigger queue on the Integration Server. A document is redelivered to a trigger
queue if the Integration Server shuts down before processing and acknowledging the
document.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

578

Odd Header
Publish Folder

Output Parameters
redeliveryCount

String Species the number of times the trigger queue on

Integration Server has received the document. The redelivery
count can be one of the following:
A value
of...

Indicates...

-1

The transport used to send the document

does not maintain a document redelivery
count. For example, a document received
from a webMethods Broker version 6.0.1 has a
redelivery count of -1. (webMethods Brokers
that are version 6.0.1 or earlier do not maintain
document redelivery counts.)
Integration Server may or may not have received
the document before.

The document has been received only once.

> 0

The number of times document has been

redelivered.

Usage Notes
If you do not want to use the exactly once processing capabilities, you can invoke the
pub.publish:getRedeliveryCount service within your trigger service. The redelivery count for a
document can provide an initial indication of whether the Integration Server has already
processed the document.
Integration Server retrieves the redelivery count for the document currently maintained
in the invoke state. That is, the Integration Server retrieves the redelivery count for the
document that caused the trigger service to execute.
When a trigger service satised by an All (AND) join condition invokes
pub.publish:getRedliveryCount, the pub.publish:getRedeliveryCount service returns the redelivery
count for the last document received by the join. For example, suppose that documents
A and B satised an All (AND) join condition. If the Integration Server receives
document A rst and document B second, when pub.publish:getRedliveryCount executes, it
retrieves the redelivery count for document B.

webMethods Integration Server Built-In Services Reference Version 9.6

579

Even Header
Publish Folder

pub.publish:publish
WmPublic. Publishes a document locally or to the messaging provider.
This service broadcasts the document (that is, distributes the document to all clients that
subscribe to it).
Input Parameters
documentTypeName

String Fully qualied name of the publishable document

type of which you are publishing an instance.
If you intend to publish the document to a messaging
provider (Broker or Universal Messaging), the
publishable document type must be in sync with the
associated provider denition. The provider denition is
a representation of the publishable document type and
its properties on the provider. In the case of Universal
Messaging, this is a channel. For Broker, it is a Broker
document type. If the document type and provider
denition are not synchronized, publication might fail.

document

Document Document (IData object) conforming to the

document type in documentTypeName .

local

String Optional. Flag specifying whether the document is

to be published locally or to the messaging provider. Set
to:
true to publish locally (to this Integration Server only).
false to publish to the messaging provider using the
messaging connection alias specied in the document
type of which you are publishing an instance. This is the
default.

If the publishable document type does not specify a

messaging provider and there is no default messaging
connection alias congured for Integration Server,
all publishes become local (that is, the local ag is set
implicitly to true).
delayUntilServiceSuccess

String Optional. Flag indicating whether the publish

should happen when the pub.publish:publish service
executes or after the top-level service successfully
completes. If the top-level service fails, Integration Server
will not publish the document. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

580

Odd Header
Publish Folder

true to delay publishing until after the top-level service

executes successfully.

Note: Integration Server does not return the status

output parameter when delayUntilServiceSuccess is set
to true.
false to publish the document when the publish service

executes. This is the default.

Output Parameters
status

String Status indicating whether the service was successful.

Integration Server reports status only for locally published
documents. A value of:
success indicates that the service executed successfully.

Note: If at least one subscribing trigger has room in its queue,

the status is set to success.
noSubscriber indicates that Integration Server does not

contain any triggers that subscribe to the document.

capacityExceeded indicates that the document could not

be placed in the queue of the subscribing trigger because the

trigger queue is currently at its maximum capacity.
Note: Integration Server reports this status only when the
wa.server.publish.local.rejectOOS property is set to true.
Usage Notes
You can use pub.publish:publish to publish documents to Universal Messaging, Broker, or
locally within Integration Server.
The messaging connection alias assigned to a publishable document type determines
the message provider to which the Integration Server publishes the document. Only
subscribers to the document type on that messaging provider will receive the published
document. The Connection alias name property for the document type species the
message provider. If there is no specied message provider alias, Integration Server
publishes the document to the provider in the default messaging connection alias.
If there is no default messaging connection alias, Integration Server publishes the
document locally.
If the messaging connection alias specied for the document type does in
documentTypeName does not exist when the pub.publish:publish service executes, Integration
Server issues a ServiceException. Make sure to code your service to handle this situation.

webMethods Integration Server Built-In Services Reference Version 9.6

581

Even Header
Publish Folder

Integration Server writes a message to the journal log whenever it rejects or discards a
document.
For a Universal Messaging connection alias the Publish Wait Time While Reconnecting value
species the number of milliseconds that a publishing service using alias will wait for a
connection to the Universal Messaging server to be re-established after the connection
fails. If Integration Server re-establishes the connection before the Publish Wait Time
While Reconnecting elapses, the publishing service continues executing. If the specied
time elapses before a connection is re-established, the publishing service ends with an
ISRuntimeException. Make sure to code your service to handle this situation.
If the pub.publish:publish services publishes a document to Broker and outbound clientside queuing is disabled (the wa.server.publish.useCSQ property is set to "never"),
Integration Server issues a ServiceException if the Broker is not available when the
service executes. Make sure to code your service to handle this situation.
If the pub.publish:publish services publishes a document to Universal Messaging and
use of the client side queue is disabled for the Universal Messaging connection alias,
Integration Server throws an ISRuntimeException if the Universal Messaging server is
not available when the service executes. Make sure to code your service to handle this
situation.
Integration Server issues a ServiceException when the dispatcher is shut down during
the execution of this service. In this situation, Integration Server does not save the data
in the outbound document store (client side queue), and the document will not appear
in the outbound document store. Make sure to code your service to handle this situation.
For more information about building a service that publishes a document locally or to a
messaging provider, see the Publish-Subscribe Developers Guide.
See Also
pub.publish:deliver
pub.publish:publishAndWait
pub.publish:envelope

pub.publish:publishAndWait
WmPublic. Broadcasts a request for a document from any client subscribed to a specic
document type. The service waits for the reply or indicates that the pub.publish:waitForReply
service should retrieve the reply later.
Note: This service can be used to publish a document to webMethods Broker or locally
only.

webMethods Integration Server Built-In Services Reference Version 9.6

582

Odd Header
Publish Folder

Input Parameters
documentTypeName

String Fully qualied name of the publishable document type

being published.
If you intend to publish the document to the webMethods
Broker, the publishable document type must be in sync with
the associated webMethods Broker document type. If the
document types are not synchronized, publication fails.

document

Document Document (IData object) conforming to the

document type in documentTypeName .

receiveDocumentType
Name

String Optional. Fully qualied name of the document type

expected as a reply. If no value is specied, the service uses
the rst reply document of any type it receives, as long as the
value of tag in the reply document envelope matches the tag
in the envelope of the published document. All other reply
documents are discarded.

local

String Optional. Flag specifying whether the document is to be

published locally or to the webMethods Broker. Set to:
true to publish locally (to this Integration Server only).
false to publish to the webMethods Broker aached to this

Integration Server. This is the default.

If the publishable document type does not specify a

messaging provider and there is no default messaging
connection alias congured for Integration Server, all
publishes become local (that is, the local ag is set implicitly
to true).
waitTime

String Optional. Time to wait (in milliseconds) for the

response to arrive. If no value is specied, the service waits
indenitely for a reply.

async

String Optional. Flag specifying whether this is an

asynchronous or synchronous publish. Set to:
true to indicate that this is an asynchronous request/reply.

After publishing the document, the Integration Server

executes the next step in the ow service immediately.
The Integration Server does not wait for a reply before
continuing service execution.

webMethods Integration Server Built-In Services Reference Version 9.6

583

Even Header
Publish Folder

Note: To retrieve the reply to an asynchronous publish,

invoke the pub.publish:waitForReply service.
false to indicate that this is a synchronous request/reply.

After publishing the document, the Integration Server waits

for a reply before executing the next step in the ow service.
This is the default.
Output Parameters
receivedDocument

Document Document (IData object) received as response. If no

matching document is received within the wait time, this will
be null.
Important: Integration Server treats all reply documents as volatile
documents. If Integration Server shuts down before processing
the reply document, the reply document is lost.

tag

String Conditional. A unique identier for a publish request.

Integration Server uses the tag value to match the request
document with its corresponding reply document.
The service produces a tag output value only when the async
eld is set to true. The tag value is required input when using
the pub.publish:waitForReply service to retrieve the reply.
Note: The tag output value is the same value that Integration
Server places in the tag eld of the request document's envelope.

status

String Status indicating whether the service was successful.

Integration Server reports status only for locally published
documents. A value of:
success indicates that the service executed successfully.

Note: If at least one subscribing trigger has room in its queue,

the status is set to success.
requestTimedOut indicates that the service timed out

(that is, the waitTime specied in the service elapsed before

Integration Server received a reply).
noSubscriber indicates that Integration Server does not
contain any triggers that subscribe to the document.
capacityExceeded indicates that the document could not

be placed in the queue of the subscribing trigger because the

trigger queue is currently at its maximum capacity.

webMethods Integration Server Built-In Services Reference Version 9.6

584

Odd Header
Publish Folder

Note: Integration Server reports this status only when the

wa.server.publish.local.rejectOOS property is set to true.
Usage Notes
You can use the pub.publish:publishAndWait service to publish a document locally or to the
Broker. You cannot use pub.publish:publishAndWait with Universal Messaging
Integration Server writes a message to the journal log whenever it rejects or discards a
document.
You can use the pub.publish:publishAndWait service to initiate a request/reply. The publishing
client broadcasts a request for information. Subscribers to the broadcast document
compose and send a reply document that contains the information the publisher
requested.
A single publish and wait request might receive many response documents. The
Integration Server that made the publish and wait request uses only the rst reply
document it receives from the webMethods Broker. The Integration Server discards all
other replies. First is arbitrarily dened. There is no guarantee provided for the order in
which the webMethods Broker processes incoming replies. If you need a reply document
from a specic client, use the pub.publish:deliverAndWait service instead.
The pub.publish:publishAndWait service can be useful in situations where multiple sources
contain the response data. For example, suppose that an enterprise uses one application
for managing customer data, another for storing master customer records, and a
mainframe system for saving customer lists. Each of these applications could answer
a published request for customer data. The publishing service will use the rst reply
document it receives.
A service can issue a publish and wait request in a synchronous or asynchronous
manner.
In a synchronous request/reply, the publishing ow service stops executing while
it waits for a response. When the service receives a reply document, the service
resumes execution. If the waitTime elapses before the service receives a reply, the
Integration Server ends the request, and the service returns a null document that
indicates that the request timed out. The Integration Server then executes the next
step in the ow service. If a reply document arrives after the ow service resumes
execution, the Integration Server rejects the document and creates a journal log
message stating that the document was rejected because there was no thread waiting
for the document.
In an asynchronous request/reply, the publishing ow service continues executing
the steps in the service after publishing the document. To retrieve the reply, the
publishing ow service must invoke the pub.publish:waitForReply service. If the wait
time elapses before the pub.publish:waitForReply service receives a document, the
pub.publish:waitForReply service returns a null document indicating that the request
timed out.

webMethods Integration Server Built-In Services Reference Version 9.6

585

Even Header
Publish Folder

A service that contains multiple asynchronous publish and wait invocations allows the
service to publish all the requests before collecting the replies. This approach can be
more ecient than publishing a request, waiting for a reply, and then publishing the
next request.
If you create a service that contains multiple asynchronous requests, make sure to
link the tag output to another eld in the pipeline. Each asynchronously published
request produces a tag eld in the pipeline. If the tag eld is not linked to another
eld, the next asynchronously published request (that is, the next execution of the
pub.publish:publishAndWait service) will overwrite the rst tag value.
For more information about building a service that follows the request/reply model, see
the Publish-Subscribe Developers Guide.
If outbound client-side queuing is disabled (the watt.server.publish.useCSQ
property is set to "never"), Integration Server throws a ServiceException if the
webMethods Broker is not available when this service executes. Make sure to code your
service to handle this situation.
See Also
pub.publish:waitForReply
pub.publish:reply
pub.publish:envelope

pub.publish:reply
WmPublic. Delivers a reply document to the requesting client.
If the replyTo envelope parameter is set, the reply document is delivered to that
destination; otherwise, the reply document is sent to the client ID of the publisher
specied in the envelope's pubId eld. This service also correctly maps the required
elds from the request document to the reply document.
Note: All reply documents are volatile documents. If the requesting Integration Server
shuts down before processing the reply document, the reply document is lost.
Note: This service can be used to send a reply document via webMethods Broker or
locally within the Integration Server
Input Parameters
receivedDocumentEnvelope

Document Optional. The envelope of the

document to which you are replying. By default
receivedDocumentEnvelope species the envelope of the
document that triggered this service. (In case of a join,
it will specify the last document that satised the join

webMethods Integration Server Built-In Services Reference Version 9.6

586

Odd Header
Publish Folder

condition.) However, you may specify the envelope of

any published document to which you want to reply.
documentTypeName

String Fully qualied name of the publishable

document type for the document that you are sending
as a reply. Keep in mind that the publisher of the
requesting document might be expecting a reply
document that conforms to specic publishable
document type.

document

Document The reply IData object. This document must

conform to the publishable document type specied in
documentTypeName .

delayUntilServiceSuccess

String Optional. Flag indicating whether the Integration

Server should publish the document when the
pub.publish:reply service executes or after the top-level
service successfully completes. If the top-level service
fails, the Integration Server will not publish the
document.
Set to:
true to delay publishing until after the top-level

service executes successfully.

false to publish the document when the publish

service executes. This is the default.

Output Parameters
None.
Usage Notes
You can use the pub.publish:reply service to publish a document locally or to the Broker.
You cannot use pub.publish:reply with Universal Messaging
A reply document can be a simple acknowledgment, or it can contain information asked
for by the publisher of the request document.
If you are building a service to reply to documents that meet join conditions, keep the
following in mind:
All (AND) join conditions. If the replying service executes because two or more
documents satised an All (AND) join condition, the Integration Server uses the
envelope of the last document that satised the join condition to determine where to
send the reply document. If you want the Integration Server to use the envelope of a
dierent document, link the envelope of that document to receivedDocumentEnvelope .
If you want to reply to all documents received as part of an All (AND) join, invoke

webMethods Integration Server Built-In Services Reference Version 9.6

587

Even Header
Publish Folder

pub.publish:reply once for each document received and map the envelope from the
received document to receivedDocumentEnvelope for each call.
Any (OR) or Only one (XOR) join conditions. If the replying service executes because
a document satised an Any (OR) or Only one (XOR) join condition, do not map
or assign a value to receivedDocumentEnvelope . It is impossible to know which
document in the Any (OR) or Only one (XOR) join will be received rst. For
example, suppose that an Only one (XOR) join condition specied document types
A and B. The Integration Server uses the envelope of the document it received rst
as the receivedDocumentEnvelope value. If you map the envelope of document A to
receivedDocumentEnvelope , but the Integration Server receives document B rst, your
replying service will fail.
Important: Services that publish or deliver a document and wait for a reply can
specify a publishable document type to which reply documents must conform. If
the reply document is not of the type specied in the receiveDocumentTypeName
parameter of the pub.publish:publishAndWait or pub.publish:deliverAndWait service, the
publishing service will wait forever for a reply. Work closely with the developer of
the publishing service to make sure that your reply document is an instance of the
correct publishable document type.
For more information about building a reply service, see the Publish-Subscribe Developers
Guide.
See Also
pub.publish:deliverAndWait
pub.publish:publishAndWait
pub.publish:envelope

pub.publish:syncToBroker
WmPublic. Synchronizes one or more publishable document types with their associated
provider denition by pushing the publishable document types to the associated
message provider.
Note: This service can be used to synchronize publishable document types with the
corresponding Broker document types on webMethods Broker only.
Input Parameters
documentTypes

String List Fully qualied names of the publishable document

types to synchronize with their associated provider denition.

webMethods Integration Server Built-In Services Reference Version 9.6

588

Odd Header
Publish Folder

Output Parameters
successfulPDTs

String List Conditional. Fully qualied names of the

publishable document types that Integration Server updated
successfully on the provider. The service only produces this
output parameter if one or more publishable document types
updated successfully.

unsuccessfulPDTs

String List Conditional. Fully qualied names of the

publishable document types that Integration Server did
not update successfully on the provider. The service only
produces this output parameter if one or more publishable
document types did not update successfully.

errors

Document List Conditional. Lists any errors that occurred

during document type synchronization.

warnings

Document List Conditional. Lists any warnings that occurred

during document type synchronization.

Usage Notes
You can use pub.publish:syncToBroker as a start up service for a package to avoid using
Software AG Designer to synchronize document types.
You can use the pub.publish:syncToBroker service with Broker only. The use of
pub.publish:syncToBroker with Universal Messaging is not supported. Use Designer to
synchronize publishable document types with corresponding provider denitions
(channels) on Universal Messaging.
The Connection alias name property for a document type species the messaging
connection alias assigned to the document type which indicates the provider to which a
document type will be pushed.
If the documentTypes parameter contains document types that are not publishable or do
not exist, Integration Server lists the errors in the errors parameter.

pub.publish:waitForReply
WmPublic. Retrieves the reply for an asynchronous request. If a reply is not available,
the Integration Server continues to wait for the document until the time specied in
the waitTime parameter of the pub.publish:deliverAndWait or pub.publish:publishAndWait service
elapses.

webMethods Integration Server Built-In Services Reference Version 9.6

589

Even Header
Publish Folder

Input Parameters
String A unique identier for the publish request for which you
are retrieving a reply. Integration Server uses the tag value
to match the request document with its corresponding reply
document.

tag

Output Parameters
receivedDocument

Document Document (IData object) received as the reply to the

request. If the request expires (that is, the waitTime elapses)
before Integration Server receives the reply document, the
receivedDocument eld contains a null document.
Important: Integration Server treats all reply documents as
volatile documents. If the Integration Server shuts down before
processing the reply document, the reply document is lost.

Usage Notes
The waitTime value of the publishing service species how long Integration Server
will keep the request open while waiting for a reply. When building an asynchronous
request/reply service, keep the following information about the waitTime in mind:
The waiting interval for the reply document starts when Integration Server executes
the request service (pub.publish:deliverAndWait or pub.publish:publishAndWait). The execution
of the pub.publish:waitForReply service does not aect the waitTime interval.
If the waitTime interval elapses before the pub.publish:waitForReply service executes, the
service immediately returns a null document which indicates that the wait time has
expired.
If Integration Server has not received the reply when the pub.publish:waitForReply
service executes, the service waits the remainder of the waitTime interval. If
Integration Server does not receive a reply by the time the waitTime interval elapses,
the request completes. The service returns a null document which indicates that the
wait time has expired.
If the reply document arrives after the waitTime interval elapses, Integration Server
rejects the document because the request is closed.
A single publish and wait request might receive many response documents. Integration
Server that made the publish and wait request uses only the rst reply document it
receives from the webMethods Broker. The Integration Server discards all other replies.
First is arbitrarily dened. There is no guarantee provided for the order in which the
webMethods Broker processes incoming replies. If you need a reply document from a
specic client, use the pub.publish:deliverAndWait service instead.

webMethods Integration Server Built-In Services Reference Version 9.6

590

Odd Header
Publish Folder

For more information about building an asynchronous request/reply service, see the
Publish-Subscribe Developers Guide.
See Also
pub.publish:deliverAndWait
pub.publish:publishAndWait

pub.publish.notification:error
WmPublic. Publishable document type that denes the document that Integration Server
generates and delivers when a trigger encounters an error or exception condition during
processing.
Note: Integration Server does not generate and return and error message when the
trigger received a document from Universal Messaging.
Integration Server generates an error document if the trigger service cannot successfully
process a document for one of the following reasons:
The trigger service encounters an exception condition (that is not an
ISRuntimeException) during execution.
Integration Server makes the maximum number of aempts to re-execute the trigger
service and the service still fails because of a transient error condition.
Some other system exception occurred.
Note: Integration Server does not generate an error document if the subscribing
trigger is part of a disabled process model version because the trigger service
associated with a disabled process model version never executes.
Integration Server delivers the error document to the client ID specied in the errorsTo
eld contained in the received document's envelope. If the errorsTo eld is empty, the
Integration Server delivers the error document to the original document's publisher (as
specied in the pubId envelope eld). The error document noties the publisher or other
designated recipient that the subscriber cannot process the document successfully.
Note: If a trigger service cannot process a locally published document successfully,
Integration Server produces and delivers an error document only if the Integration
Server is connected to a webMethods Broker.
Parameters
adapterType

String Optional. The resource producing the error. Integration

Server sets the value of this eld to Integration Server.

webMethods Integration Server Built-In Services Reference Version 9.6

591

Even Header
Publish Folder

errorCategory

String Optional. Type of exception. Integration Server sets the

value of this eld to Application.

errorText

String Optional. Exception text message. At Dispatcher debug

level 9, a stack trace of the exception will also be returned.

eventID

java.lang.Long Optional. The event ID of the document that

caused this exception. If the trigger service executed because
a document satised a join condition, then the eventID is the
event ID of the last document that satised the condition.

_env

Document Optional. A document reference to the

pub.publish:envelope document type.

Usage Notes
The client to which Integration Server delivers the error document needs to subscribe
to the pub.publish.notification:error document type. If the client does not have a trigger that
subscribes to this document type, the client will never receive or process the error
document. If the client receiving the error document is an Integration Server, it generates
the message [ISS.0098.0024V2] No trigger available for incoming Document
pub.publish.notification:error.
See Also
pub.publish:envelope

webMethods Integration Server Built-In Services Reference Version 9.6

592

Odd Header
Remote Folder

24 Remote Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

594

593

Even Header
Remote Folder

You use the elements in the remote folder to invoke services on other webMethods
Integration Server.
You can also use remote services for guaranteed delivery transactions. For more
information about guaranteed delivery transactions, see the Guaranteed Delivery
Developers Guide and webMethods Integration Server Administrators Guide.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.remote:invoke

WmPublic. Invokes a service on a remote

webMethods Integration Server.

pub.remote.gd:end

WmPublic. Ends a guaranteed delivery transaction.

pub.remote.gd:getStatus

WmPublic. Returns the status of the guaranteed

delivery transaction.

pub.remote.gd:invoke

WmPublic. Invokes the service for a guaranteed

delivery transaction by making a synchronous call to
a remote webMethods Integration Server.

pub.remote.gd:restart

WmPublic. Restarts an expired guaranteed delivery

transaction.

pub.remote.gd:retrieve

WmPublic. Retrieves the results of a guaranteed

delivery transaction submied asynchronously or
synchronously to a remote webMethods Integration
Server.

pub.remote.gd:send

WmPublic. Makes a guaranteed one-way call (reand-forget) to the webMethods Integration Server
to invoke a service for which no output is needed or
expected.

pub.remote.gd:start

WmPublic. Starts a guaranteed delivery transaction.

pub.remote.gd:submit

WmPublic. Invokes a service for a guaranteed

delivery transaction by making an asynchronous call
to a remote webMethods Integration Server.

webMethods Integration Server Built-In Services Reference Version 9.6

594

Odd Header
Remote Folder

pub.remote:invoke
WmPublic. Invokes a service on a remote webMethods Integration Server.
The remote server is identied by an alias, which is congured on the Remote Servers tab
in the Integration Server Administrator. Connection and authentication to the remote
server is managed transparently to the caller of this service.
All current pipeline inputs are passed to the remote service. To improve performance
and minimize the amount of data sent over the wire, scope the pipeline to a separate
document or drop unneeded elds before invoking this service. The same advice applies
to the output values of the remote service because all values returned from the service
are sent over the wire in response to the caller.
Input Parameters
$alias

String Name of the target server on which to invoke the

specied service. This name and its associated connection
aributes are dened on the Create Remote Server Alias screen in
the Integration Server Administrator.
Note: If you protect the alias using an Access Control List,
the user invoking invoke must be a member of this list or the
invocation will fail.

$service

String Fully qualied name of the service to invoke on the

remote server, in the format folderName.folderName:serviceName
(for example: wm.server:ping).

$scope

String Flag that species how the session to the remote server
should be managed. Set to:
SESSION to store the remote session in the current user

session. This is the default.

Further calls by the same user to pub.remote:invoke for the same

server alias reuse the existing remote session with the server.
Stateful interactions with the remote server are maintained
and protected inside the current user's session.
When the current user disconnects, the remote session
expires, or the local server is shut down, the remote session is
automatically disconnected.
GLOBAL to tore the remote session in a shared pool of

sessions. If another user invokes a service on the same remote

server with GLOBAL scope, the session will be reused.

webMethods Integration Server Built-In Services Reference Version 9.6

595

Even Header
Remote Folder

Stateful interactions with the remote server could be

destroyed by other users' invocations.
When the remote session expires due to inactivity or the
local server is shut down, the remote session is automatically
disconnected.
$close

String Optional. Flag to indicate whether Integration

Servercloses the connection to the remote server after the
service invocation or keeps the connection open until it times
out. Set to:
true to close the connection to the remote server

immediately after the service invocation.

false to keep the connection open until it times out. This is

the default.
$clusterRetry

String Optional. Flag to indicate whether Integration

Servershould retry a failed connection request on other
Integration Servers in the cluster. Set to:
true to retry a request automatically on other Integration

Servers in the cluster if the initial aempt to connect to

a remote Integration Server fails. Integration Serverwill
aempt to connect to each Integration Servers in the cluster
until the connection is made or all Integration Servers have
been tried with no success. If the service cannot connect to
another Integration Server in the cluster, the service tries to
connect to the retry server specied in the alias denition for
the remote server.
false to issue an error if the aempt to connect to the remote

Integration Server fails. If the alias denition for the remote

server species a retry server, the service tries to connect to
that server.
Note: Once a connection to a remote server has been
established, that connection is cached and reused. The
$clusterRetry seing is established when the connection
is rst created and used. Subsequent invokes to the same
remote server will not change the $clusterRetry seing,
even if a dierent value is passed in the pipeline. Client
applications must determine whether or not they want
cluster retries before establishing the connection.

webMethods Integration Server Built-In Services Reference Version 9.6

596

Odd Header
Remote Folder

Output Parameters
Returns the output of the invoked service. The output signature matches the output
signature of the invoked service.
Usage Notes
If pub.remote:invoke does not receive a response within the timeout period specied
in the server's watt.net.timeout parameter, it will throw an exception. For
information about the watt.net.timeout parameter, see webMethods Integration Server
Administrators Guide.

pub.remote.gd:end
WmPublic. Ends a guaranteed delivery transaction.
Input Parameters
tid

String Transaction ID of the transaction you want to end.

Output Parameters
None.
Usage Notes
This service is used to eliminate a guaranteed delivery transaction from the jobstore.

pub.remote.gd:getStatus
WmPublic. Returns the status of the guaranteed delivery transaction.
Input Parameters
tid

String Transaction identication number.

Output Parameters
status

String Current status of the transaction. status can have one of

the following values:
NEW indicates that the transaction is new.
PENDING indicates that the transaction is pending.

webMethods Integration Server Built-In Services Reference Version 9.6

597

Even Header
Remote Folder

DONE indicates that the transaction is completed.

FAILED indicates that the transaction expired because the

time-to-live or the retry limit has been exceeded.

UNKNOWN indicates that the transaction identication number

in tid is not recognized.

Usage Notes

Use the pub.remote.gd:restart service to restart a FAILED (expired) guaranteed delivery

transaction.

pub.remote.gd:invoke
WmPublic. Invokes the service for a guaranteed delivery transaction by making a
synchronous call to a remote webMethods Integration Server.
Input Parameters
service

String Name of the service to be run on the remote

webMethods Integration Server.

tid

String Transaction identication number for the service.

inputs

Document Optional. Document (IData object) containing the

inputs for the service.

Output Parameters
results

Document Conditional. Document (IData object) containing the

pipeline as it exists after the service is invoked.

Usage Notes
To use an asynchronous call to the server to invoke a service for a guaranteed delivery
transaction, use the pub.remote.gd:submit service.
If the remote server does not respond within the timeout limit specied in this server's
watt.net.timeout seing, the Integration Server treats it as a failed aempt and retries
the request.

webMethods Integration Server Built-In Services Reference Version 9.6

598

Odd Header
Remote Folder

pub.remote.gd:restart
WmPublic. Restarts an expired guaranteed delivery transaction.
Input Parameters
tid

String Transaction identication number for the guaranteed

delivery transaction you want to restart.

Output Parameters
None.
Usage Notes
If a guaranteed delivery transaction failed because of server or network failure, use this
service to restart the transaction without resubmiing it.

pub.remote.gd:retrieve
WmPublic. Retrieves the results of a guaranteed delivery transaction submied
asynchronously or synchronously to a remote webMethods Integration Server.
Input Parameters
tid

String Transaction identication number.

block

String Optional. Flag that species whether to block or poll for

the results of the transaction. Set to:
true to wait until the invoked service completes before

retrieving results. This is also known as blocking mode. This

is the default.
false to retrieve the results immediately, whether or not the

invoked service is completed. This is also known as polling

mode.
Output Parameters
results

Document Conditional. Document (IData object) containing the

results of the service in the guaranteed delivery transaction.

webMethods Integration Server Built-In Services Reference Version 9.6

599

Even Header
Remote Folder

Usage Notes
If block is false, and the results of the transaction are still pending when this service
executes, the results are returned as null.

pub.remote.gd:send
WmPublic. Makes a guaranteed one-way call (re-and-forget) to the webMethods
Integration Server to invoke a service for which no output is needed or expected.
Input Parameters
service

String Service to be run on the remote Integration Server.

tid

String Transaction identication number for the service.

inputs

Document Optional. Document (IData object) containing the

inputs for the service.

Output Parameters
None.
Usage Notes
The results of the service specied in service cannot be retrieved. However, errors that
occur will be logged when the guaranteed delivery transaction ends.
Use the pub.remote.gd:send service to invoke a service remotely only if you want to run a
guaranteed delivery transaction and are not concerned about the results of the invoked
service. After pub.remote.gd:send completes the call, the service ends the transaction;
therefore, you do not need to use the pub.remote.gd:end service to end the transaction.

pub.remote.gd:start
WmPublic. Starts a guaranteed delivery transaction.
Input Parameters
alias

String Name of the webMethods Integration Server on which

you want to invoke a guaranteed delivery transaction. This
name and its associated connection aributes are dened on
the Remote Servers tab of the Integration Server Administrator.

webMethods Integration Server Built-In Services Reference Version 9.6

600

Odd Header
Remote Folder

String Optional. Transaction time-to-live measured in minutes.

The transaction expires when l is exceeded.
Default is the value set in the watt.tx.defaultTTLMins
property or, if the property is not set, 30 minutes.

retries

String Optional. Maximum number of times to retry the

transaction. Default is 0 (no retry limit).

followtid

String Optional. Identication number of the transaction

you want this guaranteed delivery transaction to follow.
The current transaction executes only after the transaction
indicated by followtid completes.

Output Parameters
tid

String Transaction identication number.

pub.remote.gd:submit
WmPublic. Invokes a service for a guaranteed delivery transaction by making an
asynchronous call to a remote webMethods Integration Server.
Input Parameters
service

String Service to be run on the remote webMethods Integration

Server.

tid

String Transaction identication number for the service.

inputs

Document Optional. Document (IData object) containing the

inputs for the service.

Output Parameters
None.
Usage Notes
To remove the transaction from the remote webMethods Integration Server, use the
pub.remote.gd:end service.
To use a synchronous call to invoke the service, use the pub.remote.gd:invoke service.

webMethods Integration Server Built-In Services Reference Version 9.6

601

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

602

Odd Header
Replicator Folder

25 Replicator Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

604

603

Even Header
Replicator Folder

You use the elements in the replicator folder to replicate packages across webMethods
Integration Servers. This folder contains services that you can use to push packages
from your webMethods Integration Servers to a subscriber's server. It also contains
services that you can use to pull packages from a publisher's server to your webMethods
Integration Server.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.replicator:addReleaseRegistryEntry

WmPublic. Adds an entry to the

webMethods Integration Server's Package
Release Registry.

pub.replicator:deleteReleaseRegistryEntry

WmPublic. Deletes an entry from the

webMethods Integration Server's Package
Release Registry.

pub.replicator:distributeViaFTP

WmPublic. Allows a publisher to send a

package to a subscriber via FTP or allows
a subscriber to retrieve a package from a
publisher via FTP.

pub.replicator:distributeViaSvcPull

WmPublic. Pulls a specied package release

from a publisher's server.

pub.replicator:distributeViaSvcPush

WmPublic. Pushes a package from your

server to a list of subscribers (other
webMethods Integration Servers).

pub.replicator:generateReplicationEvent

WmPublic. Generates a replication event.

pub.replicator:getLocalReleasedList

WmPublic. Returns all entries in your

webMethods Integration Server's Package
Release Registry.

pub.replicator:getRemoteReleasedList

WmPublic. Queries the publisher for

released packages.

pub.replicator:notifyPackageRelease

WmPublic. Sends an e-mail message to

subscribers who have said that they want

webMethods Integration Server Built-In Services Reference Version 9.6

604

Odd Header
Replicator Folder

Element

Package and Description

to be notied when a new release becomes
available.

pub.replicator:packageCreation

WmPublic. Creates a distribution le (a zip

le) for the package.

pub.replicator:addReleaseRegistryEntry
WmPublic. Adds an entry to the webMethods Integration Server's Package Release
Registry.
Input Parameters
package

String Name of the package. The service conrms that this

package exists on the server before adding an entry to the
Package Release Registry.

name

String Name of the release. This name could be dierent from

the name of the package.

version

String Version number of the release, in the format #.# or #.#.#

(for example, 1.2 or 1.2.1).

build

String Build number of the release (for example, 12, 530).

patchNums

String One or more comma-separated patch numbers included

in this release.

JVMVersion

String Minimum JVM version number that this release

requires.

description

String Brief description of this release. You may want to use

this parameter to summarize the nature and purpose of the
release.

Output Parameters
packages

Document List Entries in the server's Package Release Registry.

Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

605

Even Header
Replicator Folder

name

String Name of the release.

version

String Version number of the release,

in the format #.# or #.#.# (for example,
1.2 or 1.2.1).

build

String Conditional. Build number of

the release (for example, 12, 530).

patch_nums

String Conditional. Comma-separated

list of patch numbers included in this
release.

time

String Time when the package was

released.

jvm_version

String Minimum JVM version number

that the release requires.

description

String Conditional. Brief description

of this release.

source_server_version

String Version number of Integration

Server that released the package.

Usage Notes
Before using this service, use pub.replicator:packageCreation to create a package zip le in the
server's outbound directory. When you use addReleaseRegistryEntry to add an entry to the
Package Release Registry, the package name you specify in package should match the
package name you specied in pub.replicator:packageCreation.

pub.replicator:deleteReleaseRegistryEntry
WmPublic. Deletes an entry from the webMethods Integration Server's Package Release
Registry.
Input Parameters
packageName

String Name of the release that you want to delete.

webMethods Integration Server Built-In Services Reference Version 9.6

606

Odd Header
Replicator Folder

Output Parameters
packages

Document List Entries that remain in the server's Package

Release Registry.
Key

Description

name

String Name of the release.

version

String Version number of the release, in

the format #.# or #.#.# (for example, 1.2
or 1.2.1).

build

String Conditional. Build number of the

release (for example, 12, 530).

patch_nums

String Conditional. Comma-separated

list of patch numbers included in this
release.

time

String Time when the package was

released.

jvm_version

String Minimum JVM version number

that the release requires.

description

String Conditional. Brief description of

the release.

source_server_version

String Version number of Integration

Server that released the package.

pub.replicator:distributeViaFTP
WmPublic. Allows a publisher to send a package to a subscriber via FTP or allows a
subscriber to retrieve a package from a publisher via FTP.
Input Parameters
packageName

String Name of the released package.

webMethods Integration Server Built-In Services Reference Version 9.6

607

Even Header
Replicator Folder

action

String Flag that species whether you want to send (put) a

package to another Integration Server or whether you want to
retrieve (get) a package from another Integration Server.
Set to:
get to retrieve a package from the publisher's server. This is

the default.

put to send a package to a subscriber's server.

serverhost

String Host name or IP address of the remote Integration

Server.

serverport

String Number of the FTP port on the remote Integration

Server.

username

String User name that your server will use to log on to the
remote Integration Server.

password

String Password that your server will use to log on to the

remote Integration Server.

Output Parameters
None.

pub.replicator:distributeViaSvcPull
WmPublic. Pulls a specied package release from a publisher's server.
Input Parameters
packageName

String Name of the release.

publisher

String Alias of the publisher's server.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

608

Odd Header
Replicator Folder

pub.replicator:distributeViaSvcPush
WmPublic. Pushes a package from your server to a list of subscribers (other
webMethods Integration Servers).
Input Parameters
packageName

String The name of the release.

subscriber

String List List of the subscriber's host names or IP addresses.

Output Parameters
None.

pub.replicator:generateReplicationEvent
WmPublic. Generates a replication event.
You might invoke this service in conjunction with other services to make the package
replication process generate an event. The replication event handler would listen for this
event and perform some prescribed action that you have specied.
Input Parameters
packageName

String Name of the package.

action

String User-dened string that describes the replication event,

such as pulled or pushed.

Output Parameters
None.

pub.replicator:getLocalReleasedList
WmPublic. Returns all entries in your webMethods Integration Server's Package Release
Registry.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

609

Even Header
Replicator Folder

Output Parameters
packages

Document List Entries in the server's Package Release Registry.

Key

Description

name

String Name of the release.

version

String Version number of the release, in

the format #.# or #.#.# (for example, 1.2
or 1.2.1).

build

String Conditional. Build number of the

release (for example, 12, 530).

patch_nums

String Conditional. Comma-separated

list of the patch numbers included in
this release.

time

String Time when the package was

released.

jvm_version

String Minimum JVM version number

that the release requires.

description

String Conditional. Brief description of

the release.

source_server_version

String Version number of webMethods

Integration Server that released the
package.

pub.replicator:getRemoteReleasedList
WmPublic. Queries the publisher for released packages.
This service gets a list of released packages to which your server subscribes. You can use
the list to nd out if any new packages, or newer versions of existing packages, have
been released.

webMethods Integration Server Built-In Services Reference Version 9.6

610

Odd Header
Replicator Folder

Input Parameters
publisher

String Alias of the publishing server.

Output Parameters
packages

Document List List of released packages on the publishing

server to which you subscribe.
Key

Description

name

String Name of the release.

version

String Version number of the release, in

the format #.# or #.#.# (for example, 1.2
or 1.2.1).

build

String Conditional. Build number of the

release (for example, 12, 530).

patch_nums

String Conditional. Comma-separated

list of the patch numbers included in
this release.

time

String Time when the package was

released.

jvm_version

String Minimum JVM version number

that the release requires.

description

String Conditional. Brief description of

the release.

source_server_version

String Version number of webMethods

Integration Server that released the
package.

pub.replicator:notifyPackageRelease
WmPublic. Sends an e-mail message to subscribers who have said that they want to be
notied when a new release becomes available.

webMethods Integration Server Built-In Services Reference Version 9.6

611

Even Header
Replicator Folder

Input Parameters
packageName

String Name of the release.

Output Parameters
None.

pub.replicator:packageCreation
WmPublic. Creates a distribution le (a zip le) for the package.
Input Parameters
package

String Name of the package.

name

String Name of the release.

version

String Version number of the release, in the format #.# or #.#.#

(for example, 1.2 or 1.2.1).

build

String Build number of the release (for example, 12, 530).

patchNums

String Comma-separated list of patch numbers included in the

release.

targetPkgVersion

String Version number of the target package. To prevent

the installation program from overwriting an existing
(higher) version of the package, this eld is checked when the
subscriber installs this package over an existing package.

targetServerVersion

String Version number of the webMethods Integration Server

that this release requires.

JVMVersion

String Minimum JVM version number that this release

requires.

description

String Brief description of this release. You might use this

parameter to summarize the nature and purpose of the release.

type

String Flag indicating the type of release. Set to:

full to indicate a full package. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

612

Odd Header
Replicator Folder

partial to indicate a patch or an update for the package.

lter

String Flag that species whether all les are to be included in

the distribution le or only selected les.
If only selected les are to be included, use this parameter in
conjunction with leList to specify which les to include.
Set to:
includeall to include all the les in the distribution le.

This is the default.

include to include selected les in the distribution le.

exclude to include all except selected les in the distribution

le.
leList

String List Names of les to include or exclude from the

distribution le, depending on the value of lter .

leNamePaern

String Paern string that species the names of les to be

included in the distribution le. The asterisk (*) is the only
wildcard character allowed in a paern string. All other
characters are treated literally (for example, *.java, *.dsp).

lesToDeleteList

String List Optional. The names of les that will be deleted

from the target package when the subscribing server installs
the package created by this service.

Output Parameters
$result

String Conditional. If the distribution le is created

successfully, this parameter contains the value OK. If the
distribution le was not created successfully, this parameter is
not present in the output signature and the service throws an
exception.

Usage Notes
After you use packageCreation to create the package, use pub.replicator:addReleaseRegistryEntry
to add an entry to the Package Release Registry. The package name you
specify in packageCreation should match the package name you specify in
pub.replicator:addReleaseRegistryEntry.

webMethods Integration Server Built-In Services Reference Version 9.6

613

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

614

Odd Header
Report Folder

26 Report Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

616

615

Even Header
Report Folder

You use the elements in the report folder to apply an output template to an IData object.
The services can be used in order to generate any type of dynamic XML, EDI, or HTML
document.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.report:runFileTemplate

WmPublic. Applies a template le to a

document (IData object).

pub.report:runFileTemplateOnPipe

WmPublic. Applies a template to the pipeline.

pub.report:runStringTemplate

WmPublic. Applies an output template to a

specied document (IData object).

pub.report:runStringTemplateOnPipe

WmPublic. Applies a template to the pipeline.

pub.report:runTemplate

WmPublic. Applies a template in a le to a

specied document (IData object).

pub.report:runTemplateOnPipe

WmPublic. Applies a template in a le to the

pipeline.

pub.report:runFileTemplate
WmPublic. Applies a template le to a document (IData object).
Input Parameters
$template

java.io.File Template le.

$values

Document Document (IData object) to bind against $template .

leEncoding

String Optional. The encoding of the template le. If

leEncoding is not specied, the default le encoding specied
in the wa.server.netEncoding server parameter or the system
le encoding will be used. Examples: SJIS, ASCII, ISO8859_1.

webMethods Integration Server Built-In Services Reference Version 9.6

616

Odd Header
Report Folder

Output Parameters
$txt

String Results from applying $template to $values .

Usage Notes
If a template is not available in a templates directory of any of the packages on the
server, you can use this service by passing in a File object representing the template.

pub.report:runFileTemplateOnPipe
WmPublic. Applies a template to the pipeline.
Input Parameters
$template

java.io.File Template le.

leEncoding

String Optional. The encoding of the template le. If

leEncoding is not specied, the default le encoding specied
in the wa.server.netEncoding server parameter or the system
le encoding will be used. Examples: SJIS, ASCII, ISO8859_1.

Output Parameters
$txt

String Results from applying $template to the pipeline.

Usage Notes
If a template is not available in a templates directory of any of the packages on the
server, you can use this service to pass a File object representing the template le.

pub.report:runStringTemplate
WmPublic. Applies an output template to a specied document (IData object).
Input Parameters
$template

String Template to apply.

$values

Document Document (IData object) to bind against $template .

webMethods Integration Server Built-In Services Reference Version 9.6

617

Even Header
Report Folder

Output Parameters
$txt

String Results from applying $template to $values .

Usage Notes
This service is typically invoked from other services that already have a template in a
String object and an IData object that will be used to bind against the template.

pub.report:runStringTemplateOnPipe
WmPublic. Applies a template to the pipeline.
Input Parameters
$template

String Template to apply to pipeline.

Output Parameters
$txt

String Result from applying $template to the pipeline.

Usage Notes
This service is typically invoked from other services that already have a template in a
String object and need the template to bind against the pipeline.

pub.report:runTemplate
WmPublic. Applies a template in a le to a specied document (IData object).
Input Parameters
$template

String Name of the template le (for example, mytemp.html or

mytemp.xml).

$package

String Name of the package where the template resides (for

example, Default).

$values

Document Document (IData object) to bind against $template .

webMethods Integration Server Built-In Services Reference Version 9.6

618

Odd Header
Report Folder

leEncoding

String Optional. The encoding of the template le. If

leEncoding is not specied, the default le encoding specied
in the wa.server.netEncoding server parameter or the system
le encoding will be used. Examples: SJIS, ASCII, ISO8859_1.

Output Parameters
$txt

String Result from applying the template to $values .

Usage Notes
The service locates the output template by its le name and the name of the package in
which it resides. To apply a template that resides in IntegrationServer_directory \packages
\Default\templates\mytemp.xml, invoke the service with the following values.
$template : mytemp.xml
$package : Default

pub.report:runTemplateOnPipe
WmPublic. Applies a template in a le to the pipeline.
Input Parameters
$template

String Name of template le (for example, mytemp.html

ormytemp.xml).

$package

String Name of the package in which the template resides (for

example, Default).

leEncoding

String Optional. The encoding of the template le. If

leEncoding is not specied, the default le encoding specied
in the wa.sever.netEncoding server parameter or the system
le encoding will be used. Examples: SJIS, ASCII, ISO8859_1.

Output Parameters
$txt

String Results from applying the template le to the pipeline.

Usage Notes
The service locates the output template by its le name and the name of the
package in which it resides. For example, to apply a template that resides in
webMethods Integration Server Built-In Services Reference Version 9.6

619

Even Header
Report Folder

IntegrationServer_directory \packages\Default\templates\mytemp.xml, invoke the

service with the following values.
$template : mytemp.xml
$package : Default

webMethods Integration Server Built-In Services Reference Version 9.6

620

Odd Header
Scheduler Folder

27 Scheduler Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

622

621

Even Header
Scheduler Folder

You use the elements in the scheduler folder to execute services at the times you specify.
Services that you schedule are referred to as user tasks or just tasks. The Scheduler feature
on the webMethods Integration Server handles execution of the tasks.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.scheduler:addComplexTask

WmPublic. Adds a complex task to the

Scheduler.

pub.scheduler:addOneTimeTask

WmPublic. Adds a task that runs only once to

the Scheduler.

pub.scheduler:addRepeatingTask

WmPublic. Adds a recurring task to the

Scheduler.

pub.scheduler:cancelTask

WmPublic. Removes a task from the

Scheduler.

pub.scheduler:getTaskIDs

WmPublic. Retrieves a list of identication

numbers for tasks currently in the Scheduler.

pub.scheduler:getTaskInfo

WmPublic. Retrieves information about a task

on the Scheduler.

pub.scheduler:getUserTaskList

WmPublic. Returns a list of scheduled user

tasks.

pub.scheduler:migrateTasksToJDBC

WmPublic. Migrates scheduled user tasks

from the Integration Server embedded
database to an external database.

pub.scheduler:resumeTask

WmPublic. Resumes a suspended task.

pub.scheduler:suspendTask

WmPublic. Suspends a task on the Scheduler.

pub.scheduler:updateComplexTask

WmPublic. Updates a complex task on the

Scheduler.

webMethods Integration Server Built-In Services Reference Version 9.6

622

Odd Header
Scheduler Folder

Element

Package and Description

pub.scheduler:updateOneTimeTask

WmPublic. Updates a one-time task on the

Scheduler.

pub.scheduler:updateRepeatingTask

WmPublic. Updates a repeating task to the

Scheduler.

pub.scheduler:addComplexTask
WmPublic. Adds a complex task to the Scheduler.
The webMethods Integration Server runs the service for a complex task on the day(s)
and time(s) that you specify either during a specied date range or indenitely.
Input Parameters
service

String Name of the service you want to schedule for execution

on the server.

description

String Text string describing this task.

target

String Server or servers on which the task is to run. (Clustered

environments only). Set to:
any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,
therefore you can specify the all option to schedule a task to
run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster.

webMethods Integration Server Built-In Services Reference Version 9.6

623

Even Header
Scheduler Folder

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for
that application. If you need to run a cleanup task against all
the databases every day, you can schedule a task to run every
day on all the servers in the cluster.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String The number of minutes (after the scheduled execution

time) after which the server is to take a special action for a late
task. You specify the action to be taken in the latenessAction
parameter, described below. The server checks scheduled
tasks at startup, and again periodically. If the server nds a
task that is overdue and has exceeded the lateness period, the
server performs the requested lateness action. If the server
nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Action to take if a task has missed its scheduled start

time by a number of minutes you specied with the lateness
parameter. Possible actions are:
run immediately or 0 - Runs the task immediately
skip and run at next scheduled interval or 1 - Skips this execution
of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.

runAsUser

String Optional. User ID under which the service is to be

executed. If you do not specify a user name, the Default
access rights are used.

inputs

Document Optional. Document (IData object) containing the

input to the scheduled service.
Note: You can also assign values to input parameters of services
using the Assign Inputs option while scheduling a task in
Integration Server Administrator.

startTime

String Optional. Time at which the task is scheduled to start,

in the format HH:mm:ss . If you do not specify a startTime , the
current time is used.

webMethods Integration Server Built-In Services Reference Version 9.6

624

Odd Header
Scheduler Folder

startDate

String Optional. Date on which the task is scheduled to start, in

the format yyyy/MM/dd . If you do not specify a startDate , the
current date is used.

endTime

String Optional. Time at which the task expires, in the format

HH:mm:ss . If you do not specify an endTime , the server uses
the current time.

endDate

String Optional. Date on which the task expires, in the format

yyyy/MM/dd . If you do not specify an endDate , the server
executes this service for an indenite period of time.

months

String List Optional. Months during which the task is scheduled

to run. Months are represented by integers between 1 and 12,
where 1 indicates January and 12 indicates December. If
you do not specify months , the task will run every month.

hours

String List Optional. Hours at which the task is scheduled to

run. Hours are represented by integers between 0 and 23. If
you do not specify hours , the task runs every hour.

minutes

String List Optional. Minutes at which the task is scheduled to

run. Minutes are represented by integers between 0 and 59. If
you do not specify minutes , the task runs every minute.

daysOfMonth

String List Optional. Days of the month on which the task is

scheduled to run. Days are represented by integers between 1
and 31. If you do not specify daysOfMonth , the task runs every
day of the month.

daysOfWeek

String List Optional. Days of the week on which the task is

scheduled to run. Days are represented by integers between 1
and 7, where 1 indicates Sunday and 7 indicates Saturday.
If you do not specify daysOfWeek , the task runs every day of
the week.

Output Parameters
taskID

String Identication number of the task added to the scheduler.

type

String Code indicating the type of task added. For this type of
task, the value of type will be complex.

taskAdded

String Indicates whether the task was successfully added to the

Scheduler. If the task was successfully added to the Scheduler,

webMethods Integration Server Built-In Services Reference Version 9.6

625

Even Header
Scheduler Folder

taskAdded contains true. If the task was not successfully

added, the server throws an exception and terminates the
service.

pub.scheduler:addOneTimeTask
WmPublic. Adds a task that runs only once to the Scheduler.
The Integration Server executes the service a single time on the date and time you
specify.
Input Parameters
service

String Name of the service you want to schedule for execution.

description

String Text string describing this task.

target

String Server or servers on which the task is to run.(Clustered

environments only). Set to:
any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,
therefore you can specify the all option to schedule a task to
run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster.

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for
that application. If you need to run a cleanup task against all
the databases every day, you can schedule a task to run every
day on all the servers in the cluster.

webMethods Integration Server Built-In Services Reference Version 9.6

626

Odd Header
Scheduler Folder

For more information about how Integration Server handles

the scheduling of tasks in a clustered environment, see the
chapter about managing services webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String The number of minutes (after the scheduled execution

time) after which the server is to take a special action for a late
task. You specify the action to be taken in the latenessAction
parameter, described below. The server checks scheduled
tasks at startup, and again periodically. If the server nds a
task that is overdue and has exceeded the lateness period, the
server performs the requested lateness action. If the server
nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Action to take if a task has missed its scheduled start

time by a number of minutes you specied with the lateness
parameter. Possible actions are:
run immediately or 0 - Runs the task immediately
skip and run at next scheduled interval or 1 - Skips this execution
of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.

runAsUser

String Optional. User ID under which the service is to be

executed. If you do not specify a user name, the Default
access rights are used.

inputs

Document Optional. Document (IData object) containing input

to the scheduled service.
Note: You can also assign values to input parameters of services
using the Assign Inputs option while scheduling a task in
Integration Server Administrator

date

String Date on which to run the service, in the format yyyy/

MM/dd .

time

String Time at which to run the service, in the format

HH:mm:ss .

webMethods Integration Server Built-In Services Reference Version 9.6

627

Even Header
Scheduler Folder

Output Parameters
taskID

String Identication number of the task added to the scheduler.

type

String Code indicating the type of task added. For this type of
task, the value of type will be once.

taskAdded

String Indicates whether the task was successfully added to the

Scheduler. If the task was successfully added to the Scheduler,
taskAdded contains true. If the task was not successfully
added, the server throws an exception and terminates the
service.

pub.scheduler:addRepeatingTask
WmPublic. Adds a recurring task to the Scheduler.
The webMethods Integration Server continually executes a repeating task at the interval
you specify.
Input Parameters
service

String Name of the service you want to schedule for execution

on the server.

description

String Text string describing this task.

target

String Server or servers on which the task is to run. (Clustered

environments only). Set to:
any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,
therefore you can specify the all option to schedule a task to
run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.

webMethods Integration Server Built-In Services Reference Version 9.6

628

Odd Header
Scheduler Folder

For more information about how Integration Server handles

the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster.

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for
that application. If you need to run a cleanup task against all
the databases every day, you can schedule a task to run every
day on all the servers in the cluster.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String The number of minutes (after the scheduled execution

time) after which the server is to take a special action for a late
task. You specify the action to be taken in the latenessAction
parameter, described below. The server checks scheduled
tasks at startup, and again periodically. If the server nds a
task that is overdue and has exceeded the lateness period, the
server performs the requested lateness action. If the server
nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Action to take if a task has missed its scheduled start

time by a number of minutes you specied with the lateness
parameter. Possible actions are:
run immediately or 0 - Runs the task immediately
skip and run at next scheduled interval or 1 - Skips this execution
of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.

runAsUser

String Optional. User ID under which the service is to be

executed. If you do not specify a user name, the Default
access rights are used.

inputs

Document Optional. Document (IData object) containing input

to the scheduled service.

webMethods Integration Server Built-In Services Reference Version 9.6

629

Even Header
Scheduler Folder

Note: You can also assign values to input parameters of services

using the Assign Inputs option while scheduling a task in
Integration Server Administrator.
startTime

String Optional. Time at which the task is scheduled to start,

in HH:mm:ss format. If you do not specify a startTime , the
current time is used.

startDate

String Optional. Date on which the task is scheduled to start,

in yyyy/MM/dd format. If you do not specify date , the current
date is used.

endTime

String Optional. Time at which the task expires, in HH:mm:ss

format. If you do not specify an endTime , the server uses the
current time.

endDate

String Optional. Date on which the task expires, in yyyy/

MM/dd format. If you do not specify an endDate , the server
executes this service for an indenite period of time.

interval

String Time interval (measured in seconds) between executions

of the task.

doNotOverlap

String Optional. Flag that indicates whether you want

executions of this task to overlap. Set to:
true to prevent executions of the scheduled task from

overlapping. After a scheduled task nishes executing, the

Scheduler waits the number of seconds specied in interval
before running the task again.
false to allow executions of the scheduled task to overlap.

The Scheduler runs the task every time the value of interval
elapses. This is the default.
Output Parameters
taskID

String Identication number of the task added to the Scheduler.

type

String Code indicating the type of task added. For this type of
task, the value of type will be repeat.

taskAdded

String Indicates whether the task was successfully added to the

Scheduler. If the task was successfully added to the Scheduler,
taskAdded contains true. If the task was not successfully

webMethods Integration Server Built-In Services Reference Version 9.6

630

Odd Header
Scheduler Folder

added, the server throws an exception and terminates the

service.

pub.scheduler:cancelTask
WmPublic. Removes a task from the Scheduler.
Input Parameters
taskID

String Identication number of the task to remove from the

Scheduler.
If your server runs as part of a cluster of servers, and you have
scheduled a task to run on all servers in the cluster, note the
following before canceling a task:
If you cancel a parent task, the task will be canceled on all
servers in the cluster.
If you cancel a child task, the task will be canceled only on
the server on which the child task was scheduled to run.
For more information about parent and child tasks, see
pub.scheduler:getTaskInfo or the chapter about managing services
in webMethods Integration Server Administrators Guide.

Output Parameters
taskCancelled

String Indicates whether the task was successfully removed

from the Scheduler. If the task was successfully removed from
the Scheduler, taskCancelled contains true. If the task was not
successfully removed, the server throws an exception and
terminates the service.

Usage Notes
For information about the tasks on the Scheduler, run the pub.scheduler:getTaskIDs and
pub.scheduler:getTaskInfo services.

pub.scheduler:getTaskIDs
WmPublic. Retrieves a list of identication numbers for tasks currently in the Scheduler.

webMethods Integration Server Built-In Services Reference Version 9.6

631

Even Header
Scheduler Folder

Input Parameters
running

String Species whether the service returns task IDs for all
tasks or just tasks that are running. If you specify false (the
default), the service returns task IDs for all tasks. If you specify
true, the service returns task IDs for just those tasks with the
status running.

Output Parameters
taskIDs

String List Identication numbers for the tasks on the

Scheduler.

pub.scheduler:getTaskInfo
WmPublic. Retrieves information about a task on the Scheduler.
Input Parameters
taskID

String Task identication number.

Output Parameters
type

String Code indicating the task's type. Will be one of the

following:
complex
once
repeat

runAsUser

String The user ID whose access rights are used to execute the
service.

target

String Server or servers on which the task is to run. (Clustered

environments only). A value of:
$any indicates that the task will run on any, but only one,

server in the cluster.

For more information about scheduled tasks in a clustered

environment, see the chapter about managing services in
webMethods Integration Server Administrators Guide.
$all indicates that the task will run on all servers in a cluster.

webMethods Integration Server Built-In Services Reference Version 9.6

632

Odd Header
Scheduler Folder

When you schedule a task to run on all servers in the cluster,

the server divides the task into a main or parent task, and
a child task for each server in the cluster. You can perform
some actions (activate, suspend, delete) individually on the
child tasks, but if you want to change the characteristics of a
task, you must do so through the parent task.
For a parent task, this service returns $all in the Target
parameter.
For each child task, this service returns the hostname:port on
which the task is to run.
For more information about scheduled tasks in a clustered
environment, see the chapter about managing services in
webMethods Integration Server Administrators Guide.
hostname indicates that the task will run on this particular

server. This service returns hostname:port if:

Your server is running in a cluster, a task was scheduled

to run on all servers in the cluster, and this is one of the
child tasks. (See the description of $all above.)
Your server is running in a cluster and you requested a
specic server.
Your server is not running in a cluster.
For more information about scheduled tasks in a
clustered environment, see the chapter about managing
services in webMethods Integration Server Administrators
Guide .
description

String Text string describing this task.

lateness

String The number of minutes (after the scheduled execution

time) after which the server is to take a special action for a late
task. You specify the action to be taken in the latenessAction
parameter, described below. The server checks scheduled
tasks at startup, and again periodically. If the server nds a
task that is overdue and has exceeded the lateness period, the
server performs the requested lateness action. If the server
nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Action to take if a task has missed its scheduled start

time by a number of minutes you specify in the lateness
parameter. Possible actions are:
run immediately or 0 - Runs the task immediately

webMethods Integration Server Built-In Services Reference Version 9.6

633

Even Header
Scheduler Folder

skip and run at next scheduled interval or 1 - Skips this execution

of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.
service

String Name of the service associated with the task.

nextRun

String Next date and time that the task is scheduled to run. The
date and time is expressed as the number of milliseconds from
January 1, 1970, 00:00:00 GMT.

execState

String Current state of the task.

Tasks can be in one of the following states:
A value of...

Indicates that...

The task is currently active.

The task is currently running.

The task has been suspended or has

expired.

For tasks that are scheduled to run on all servers in the cluster,
you might see dierent statuses among the parent and child
tasks. For example, the parent's status might be Active, while
one child's status is Active, and another child's status is
Suspended.
In general, the status of the parent task will be Active if at least
one child task is active or running, Suspended if all child tasks
are suspended, or Expired, if all child tasks are expired.
inputs

Document Conditional. Document (IData object) containing the

inputs, if any, to the scheduled service.

oneTimeTaskInfo

Document Conditional. Information about the complex task

represented by taskID . This parameter is present only if type is
once.
Key

Description

date

String Conditional. Date on which to run

the task, in yyyy/MM/dd format.

webMethods Integration Server Built-In Services Reference Version 9.6

634

Odd Header
Scheduler Folder

time
repeatingTaskInfo

complexTaskInfo

String Conditional. Time at which to run

the task, in HH:mm:ss format.

Document Conditional. Information about the task represented

by taskID . This parameter is present only if type is repeat.
Key

Description

interval

String Conditional. Time interval

(measured in seconds) between
repetitions of the task.

doNotOverlap

String Conditional. Indicates whether

recurrences of this task will overlap.

Document Conditional. Information about the task. This

parameter is present only if type is complex.
Key

Description

startDate

String Conditional. Date on which the

task is scheduled to start, in yyyy/MM/
dd format.

startTime

String Conditional. Time at which the

task is scheduled to start, in HH:mm:ss
format.

endDate

String Conditional. Date on which the

task expires, in yyyy/MM/dd format.

endTime

String Conditional. Time at which the

task expires, in HH:mm:ss format.

minutes

String List Conditional. Minutes at which

the task is scheduled to run. Minutes are
represented by integers between 0 and
59.

hours

String List Conditional. Hours when

the task is scheduled to run. Hours are
represented by integers between 0 and
23.

webMethods Integration Server Built-In Services Reference Version 9.6

635

Even Header
Scheduler Folder

months

String List Conditional. Months during

which the task is scheduled to run.
Months are represented by integers
between 1 and 12, where 1 indicates
January and 12 indicates December.

daysOfWeek

String List Conditional. Days of the

week on which the task is scheduled to
run. Days are represented by integers
between 1 and 7, where 1 indicates
Sunday and 7 indicates Saturday.

daysOfMonth

String List Conditional. Days of the

month on which the task is scheduled
to run. Days are represented by integers
between 1 and 31.

pub.scheduler:getUserTaskList
WmPublic. Returns a list of scheduled user tasks.
Input Parameters
None.
Output Parameters
tasks

Document List List of one-time and simple repeating tasks.

extTasks

Document List List of complex repeating tasks.

pub.scheduler:migrateTasksToJDBC
WmPublic. Migrates scheduled user tasks from the Integration Server embedded
database to an external database.
Integration Server stores information about certicate maps and scheduled jobs in
a database that is associated with the ISInternal functional alias. When you install
Integration Server, you can select whether this database will exist as an embedded
database that is shipped with Integration Server, or an external RDBMS that you set
up. If you chose to use the embedded database at install time, but later want to use an
external RDBMS instead, you can use the pub.scheduler:migrateTasksToJDBC service to copy

webMethods Integration Server Built-In Services Reference Version 9.6

636

Odd Header
Scheduler Folder

or move information about user scheduled tasks from the embedded database to the
external RDBMS.
Input Parameters
move

Boolean Species whether the tasks are to be deleted from

the embedded database after the migration successfully
completes. If set to false, the default, the tasks remain
in the embedded database. If set to true, the tasks are
removed from the embedded database.

Output Parameters
numberOfTaskMigrated

String The number of user scheduled tasks that were

migrated.

successful

String Indicates whether or not the migration was

successful. The service returns true if all tasks were
successfully migrated, otherwise false.

Usage Notes
This service copies scheduled user tasks only; it does not copy or move information
about certicate maps.
Before running this service you must install the external IS Internal database component
and dene a database connection for it. For instructions, refer to Installing webMethods
and Intelligent Business Operations Products.
When you run the service, it looks in the embedded database for scheduled user tasks
and writes any tasks it nds to the database identied by the ISInternal functional
alias, which is dened on the Settings > JDBC Pools screen of the Integration Server
Administrator.

pub.scheduler:resumeTask
WmPublic. Resumes a suspended task.
Input Parameters
taskID

String Identication number of the task to resume.

If your server runs as part of a cluster of servers, and you have
scheduled a task to run on all servers in the cluster, note the
following before resuming a task:

webMethods Integration Server Built-In Services Reference Version 9.6

637

Even Header
Scheduler Folder

If you resume a parent task, the task will be resumed on all

servers in the cluster.
If you resume a child task, the task will be resumed only on
the server on which the child task was scheduled to run.
For more information about parent and child tasks, see
pub.scheduler:getTaskInfo or the chapter about managing services
in webMethods Integration Server Administrators Guide.
Output Parameters
taskResumed

String Indicates whether the task was successfully resumed. If

the task was successfully resumed, taskResumed contains true.
If the task was not successfully resumed, the server throws an
exception and terminates the service.

pub.scheduler:suspendTask
WmPublic. Suspends a task on the Scheduler.
Input Parameters
taskID

String Identication number of the task to suspend.

If your server runs as part of a cluster of servers, and you have
scheduled a task to run on all servers in the cluster, note the
following before canceling a task:
If you suspend a parent task, the task will be suspended on
all servers in the cluster.
If you suspend a child task, the task will be suspended only
on the server on which the child task was scheduled to run.
For more information about parent and child tasks, see
pub.scheduler:getTaskInfo or the chapter about managing services
in webMethods Integration Server Administrators Guide.

Output Parameters
taskSuspended

String Indicates whether the task was successfully suspended.

If the task was successfully suspended, taskSuspended contains
true. If the task was not successfully suspended, the server
throws an exception and terminates the service.

webMethods Integration Server Built-In Services Reference Version 9.6

638

Odd Header
Scheduler Folder

Usage Notes
If you want to cancel a task or remove a task from the scheduler, use the
pub.scheduler:cancelTask service.

pub.scheduler:updateComplexTask
WmPublic. Updates a complex task on the Scheduler.
The webMethods Integration Server runs the service for a complex task on the day(s)
and time(s) that you specify either during a specied date range or indenitely.
Input Parameters
taskID

String Identication number of the task to be updated.

service

String Optional. Name of the service you want to schedule for

execution on the server.

description

String Optional. Text string describing this task.

target

String Optional. Server or servers on which the task is to run.

(Clustered environments only). Set to:
any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,
therefore you can specify the all option to schedule a task to
run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster. For clustered

environments only.

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for

webMethods Integration Server Built-In Services Reference Version 9.6

639

Even Header
Scheduler Folder

that application. If you need to run a cleanup task against all

the databases every day, you can schedule a task to run every
day on all the servers in the cluster.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String Optional. The number of minutes (after the scheduled

execution time) after which the server is to take a special
action for a late task. You specify the action to be taken in the
latenessAction parameter, described below. The server checks
scheduled tasks at startup, and again periodically. If the server
nds a task that is overdue and has exceeded the lateness
period, the server performs the requested lateness action. If the
server nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Optional. Action to take if a task has missed its

scheduled start time by a number of minutes you specied
with the lateness parameter. Possible actions are:
run immediately or 0 - Runs the task immediately
skip and run at next scheduled interval or 1 - Skips this execution
of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.

doNotOverlap

String Optional. Flag that indicates whether you want

executions of this task to overlap. Set to:
true to prevent executions of the scheduled task from

overlapping. After a scheduled task nishes executing, the

Scheduler waits the number of seconds specied in interval
before running the task again.
false to allow executions of the scheduled task to overlap.
The Scheduler runs the task every time the value of interval
elapses. This is the default.
runAsUser

String Optional. User ID under which the service is to be

executed. If you do not specify a user name, the Default
access rights are used.

webMethods Integration Server Built-In Services Reference Version 9.6

640

Odd Header
Scheduler Folder

inputs

Document Optional. Document (IData object) containing input

to the scheduled service.

startTime

String Optional. Time at which the task is scheduled to start,

in HH:mm:ss format. If you do not specify a startTime , the
current time is used.

startDate

String Optional. Date on which the task is scheduled to start,

in yyyy/MM/dd format. If you do not specify date , the current
date is used.

endTime

String Optional. Time at which the task expires, in HH:mm:ss

format. If you do not specify an endTime , the server uses the
current time.

endDate

String Optional. Date on which the task expires, in yyyy/

MM/dd format. If you do not specify an endDate , the server
executes this service for an indenite period of time.

months

String List Optional. Months during which the task is scheduled

to run. Months are represented by integers between 1 and 12,
where 1 indicates January and 12 indicates December. If
you do not specify months , the task will run every month.

hours

String List Optional. Hours at which the task is scheduled to

run. Hours are represented by integers between 0 and 23. If
you do not specify hours , the task runs every hour.

minutes

String List Optional. Minutes at which the task is scheduled to

run. Minutes are represented by integers between 0 and 59. If
you do not specify minutes , the task runs every minute.

daysOfMonth

String List Optional. Days of the month on which the task is

scheduled to run. Days are represented by integers between 1
and 31. If you do not specify daysOfMonth , the task runs every
day of the month.

daysOfWeek

String List Optional. Days of the week on which the task is

scheduled to run. Days are represented by integers between 1
and 7, where 1 indicates Sunday and 7 indicates Saturday.
If you do not specify daysOfWeek , the task runs every day of
the week.

webMethods Integration Server Built-In Services Reference Version 9.6

641

Even Header
Scheduler Folder

Output Parameters
type

String Code indicating the type of task that was updated. For
this type of task, the value of type will be complex.

taskUpdated

String Indicates whether the task was successfully updated. If

the task was successfully updated, taskUpdated contains true.
If the task was not successfully updated, the server throws an
exception and terminates the service.

Usage Notes
You can use pub.scheduler:getTaskIDs and pub.scheduler:getTaskInfo services to get information
about the task you want to update.
This service updates only the elds for which you provide input parameters. If you want
to clear the information in an optional eld, specify blanks in the parameter for that
eld.
You can also assign values to input parameters of services using the Assign Inputs option
while scheduling a task in Integration Server Administrator.

pub.scheduler:updateOneTimeTask
WmPublic. Updates a one-time task on the Scheduler.
Input Parameters
taskID

String Identication number of the task to be updated.

service

String Optional. Name of the service to be scheduled.

description

String Optional. Text string describing this task.

target

String Optional. Server or servers on which the task is to run.

(Clustered environments only). Set to:
any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,

webMethods Integration Server Built-In Services Reference Version 9.6

642

Odd Header
Scheduler Folder

therefore you can specify the all option to schedule a task to

run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster.

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for
that application. If you need to run a cleanup task against all
the databases every day, you can schedule a task to run every
day on all the servers in the cluster.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String Optional. The number of minutes (after the scheduled

execution time) after which the server is to take a special
action for a late task. You specify the action to be taken in the
latenessAction parameter, described below. The server checks
scheduled tasks at startup, and again periodically. If the server
nds a task that is overdue and has exceeded the lateness
period, the server performs the requested lateness action. If the
server nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Optional. Action to take if a task has missed its

scheduled start time by a number of minutes you specied
with the lateness parameter. Possible actions are:
run immediately or 0 - Runs the task immediately
skip and run at next scheduled interval or 1 - Skips this execution
of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.

runAsUser

String Optional. User ID under which the service is to be

executed.

webMethods Integration Server Built-In Services Reference Version 9.6

643

Even Header
Scheduler Folder

inputs

Document Optional. Document (IData object) containing inputs

to the scheduled service.

date

String Optional. Date on which to run the task, in yyyy/MM/dd

format.

time

String Optional. Time at which to run the service, in HH:mm:ss

format.

Output Parameters
type

String Code indicating the type of task that was updated. For
this type of task, the value of type will be once.

taskUpdated

String Indicates whether the task was successfully updated. If

the task was successfully updated, taskUpdated contains true.
If the task was not successfully updated, the server throws an
exception and terminates the service.

Usage Notes
This service updates only the elds for which you provide input parameters. If you want
to clear the information in an optional eld, specify blanks in the parameter for that
eld.
You can also assign values to input parameters of services using the Assign Inputs option
while scheduling a task in Integration Server Administrator.

pub.scheduler:updateRepeatingTask
WmPublic. Updates a repeating task to the Scheduler.
Input Parameters
taskID

String Identication number of the task to be updated.

service

String Optional. Name of the service run by the task.

description

String Optional. Text string describing this task.

target

String Optional. Server or servers in the cluster on which the

task is to run. (Clustered environments only). Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

644

Odd Header
Scheduler Folder

any to run the task on any server in the cluster. The task will

run on only one of the servers.

For example, suppose that all the servers in your cluster

share a single database for a parts inventory application,
and that a particular function needs to run against that
database once a day. Any of the servers can perform this task,
therefore you can specify the all option to schedule a task to
run on any of the servers.
Note: There is no predetermined order in which servers in
the cluster are selected to run tasks. Rather, the rst server to
detect that a task is ready to be executed runs it.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
all to run the task on all servers in the cluster.

For example, suppose you run an application on each server

in the cluster, and each server maintains its own database for
that application. If you need to run a cleanup task against all
the databases every day, you can schedule a task to run every
day on all the servers in the cluster.
For more information about how Integration Server handles
the scheduling of tasks in a clustered environment, see the
chapter about managing services in webMethods Integration
Server Administrators Guide.
hostname to run the task on a specic server in the cluster.

lateness

String Optional. The number of minutes (after the scheduled

execution time) after which the server is to take a special
action for a late task. You specify the action to be taken in the
latenessAction parameter, described below. The server checks
scheduled tasks at startup, and again periodically. If the server
nds a task that is overdue and has exceeded the lateness
period, the server performs the requested lateness action. If the
server nds a task that is overdue but has not yet exceeded the
lateness period, the server starts the task immediately.

latenessAction

String Optional. Action to take if a task has missed its

scheduled start time by a number of minutes you specied
with the lateness parameter. Possible actions are:
run immediately or 0 - Runs the task immediately

webMethods Integration Server Built-In Services Reference Version 9.6

645

Even Header
Scheduler Folder

skip and run at next scheduled interval or 1 - Skips this execution

of the task and runs it again at the next scheduled run time.
suspend or 2 - Places the task in a suspended state until an
administrator resumes or cancels the task.
runAsUser

String Optional. User ID under which the service is to be

executed. If you do not specify a user name, the Default
access rights are used.

startTime

String Optional. Time at which the task is scheduled to start,

in HH:mm:ss format. If you do not specify a startTime , the
current time is used.

startDate

String Optional. Date on which the task is scheduled to start,

in yyyy/MM/dd format. If you do not specify date , the current
date is used.

endTime

String Optional. Time at which the task expires, in HH:mm:ss

format. If you do not specify an endTime , the server uses the
current time.

endDate

String Optional. Date on which the task expires, in yyyy/

MM/dd format. If you do not specify an endDate , the server
executes this service for an indenite period of time.

inputs

Document Optional. Document (IData object) containing inputs

to the scheduled service.

interval

String Optional. Time interval (measured in seconds) between

repetitions of the task.

doNotOverlap

String Optional. Flag indicating whether or not you want the

executions of this task to overlap. Set to:
true to prevent executions of the scheduled task from

overlapping. After a scheduled task nishes executing, the

Scheduler waits the number of seconds specied in interval
before running the task again.
false to allow executions of the scheduled task to overlap.

The Scheduler runs the task every time the value of interval
elapses. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

646

Odd Header
Scheduler Folder

Output Parameters
type

String Code indicating the type of task updated. For this type
of task, the value of type will be repeat.

taskUpdated

String Indicates whether the task was successfully updated. If

the task was successfully updated, taskUpdated contains true.
If the task was not successfully updated, the server throws an
exception and terminates the service.

Usage Notes
This service updates only the elds for which you provide input parameters. If you want
to clear the information in an optional eld, specify blanks in the parameter for that
eld.
You can also assign values to input parameters of services using the Assign Inputs option
while scheduling a task in Integration Server Administrator.

webMethods Integration Server Built-In Services Reference Version 9.6

647

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

648

Odd Header
Schema Folder

28 Schema Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

650

649

Even Header
Schema Folder

You use the elements in the schema folder to validate objects and to validate the
pipeline.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.schema:createXSD

WmPublic. Creates an XML Schema denition

from a document type, from the input and output
parameters of a service, or from a specication.

pub.schema:validate

WmPublic. Validates an object using an IS

document type or a schema.

pub.schema:validatePipeline

WmPublic. Validates the pipeline against a

document type.

pub.schema.w3c

WmPublic. This folder contains denitions for

XML Schemas as dened in the W3C specication
XML Schema Part 2: Datatypes.

pub.schema.w3c:datatypes

WmPublic. A schema containing the simple type

names for built-in schemas.

pub.schema.w3c:structures

WmPublic. A schema containing the structural

components for XML schema denitions.

pub.schema.w3c:xml

WmPublic. A schema containing the XML

namespace components, such as xml:lang and
xml:space, as dened in the W3C specications
Namespaces in XML and Extensible Markup Language
(XML) 1.0.

pub.schema.w3c:xsi

WmPublic. A schema containing the XML

Schema instance components, such as
xsi:nil, xsi:noNamespaceSchemaLocation,
xsi:schemaLocation, and xsi:type, as dened in
the W3C XML Schema recommendation Part 1:
Structures.

webMethods Integration Server Built-In Services Reference Version 9.6

650

Odd Header
Schema Folder

pub.schema:createXSD
WmPublic. Creates an XML Schema denition from a document type, from the input
and output parameters of a service, or from a specication.
Input Parameters
name

String Fully qualied name of a document type, service, or

specication on the Integration Server.

Output Parameters
isSuccessful

String Flag indicating whether the schema denition was

created successfully. A value of:
true indicates that the schema denition was created

successfully.

false indicates that the schema denition was not created

successfully. See errors for detailed information.

xsd

errors

Document Conditional. The schema denition xsd has the

following keys:
Key

Description

url

String Conditional. Relative url of the

generated schema.

source

String Conditional. Schema denition.

Document List Conditional. List of fatal errors, if any, that

occurred when generating the XSD. Each document in the list
has the following structure:
Key

Description

error Message

String Text of the error message.

When fatal errors occur, the service does not generate an XSD
le.

webMethods Integration Server Built-In Services Reference Version 9.6

651

Even Header
Schema Folder

warnings

Document List Conditional. List of non-fatal errors, if any, that

were encountered while generating the XSD. Each document
in the list has the following structure:
Key

Description

warningMessage

String Text of the warning message.

When non-fatal errors occur, the service generates the XSD

le but also returns warnings to indicate that it encountered
unusual or unexpected conditions during the process.
Usage Notes
If the document type, service signature, or specication you are providing as input to
createXSD contains elds that belong to multiple XML namespaces, createXSD generates
multiple XML Schema denitions (one for each XML namespace) and imports them into
the XML Schema contained in the source eld. These imported XML Schema denitions
appear as children of xsd in the pipeline.
When using createXSD to create an XML Schema denition, keep the following points in
mind:
Top-level strings are not allowed.
String tables beneath the top level are not allowed.
Field names must conform to QName lexical rules (that is, the prex and local name
must conform to NCName rules specied in hp://www.w3.org/TR/REC-xmlnames/#NT-NCName).
Field names cannot contain a prex without an associated XML namespace.
Fields of type other than scalar string cannot have names that begin with the
character @ or be named *body.
Fields at the same level (that is, beneath the same parent eld in the input or output
of the same signature) can have the same name but dierent types or properties.
However, only one eld's type and properties is used for all elds with that name
at that level. Because the method used to select the eld is not dened, Software AG
recommends avoiding this case.
Only one eld named *body can occur at the same level.
Duplicate eld names that begin with the character @ cannot repeat at the same level.
Fields at dierent levels can have the same name with duplicate XML namespace
values, even if the elds have dierent types or properties. However, only one eld's
type and properties are used for all elds with that name at that level. Because the
method used to select the eld is not dened, Software AG recommends avoiding
this case.

webMethods Integration Server Built-In Services Reference Version 9.6

652

Odd Header
Schema Folder

Object constraints are allowed. However, the Integration Server does not represent
them in the XSD.
Strings constrained by older schema types (types dened before the W3C XML 2001
Schema recommendations) are allowed. However, the Integration Server translates
them into 2001 XML Schema types.
It a document variable is considered to be open (the Allow unspecied elds
property is set to true), Integration Server adds an xsd:any element to the complex
type denition that corresponds to the document variable. However, when the
wa.core.schema.createSchema.omitXSDAny sever conguration parameter is set
to true, Integration Server omits the xsd:any element even when the document
is considered to be open. For more information about this server conguration
parameter, see webMethods Integration Server Administrators Guide.
If you use createXSD to create multiple XML Schema denitions that refer to each other,
place the XSD les in the same folder or base path. To ensure that the references resolve
correctly, make sure the relative URLs specied in the XSD les reect the names of the
XSD les within this folder or base path.

pub.schema:validate
WmPublic. Validates an object using an IS document type or a schema.
Input Parameters
object

Document or com.wm.lang.xml.Document or com.wm.lang.xml.Node

Object to be validated.

conformsTo

String Document type or schema to validate object against.

If object is a document (IData object), conformsTo must
specify the fully qualied name of a document type on the
Integration Server.
If object is a com.wm.lang.xml.Document or com.wm.lang.xml.Node
object, conformsTo must specify the fully qualied name of an
IS schema on the Integration Server.
The specied IS schema is needed only for validating nodes
with "Names" that are not from XML namespaces (that is,
qualied nodes whose XML Namespace Name properties are
absent). Integration Server can only locate the IS schema if its
fully qualied name is provided.
If the XML document (com.wm.lang.xml.Document or
com.wm.lang.xml.Node) contains namespace-qualied tags,
conformsTo is ignored. Instead, Integration Server uses the
XML namespaces declared in the instance document to locate

webMethods Integration Server Built-In Services Reference Version 9.6

653

Even Header
Schema Folder

the IS schemas that contain denitions and declarations for

that XML namespace.
Note: When validating a document type created from an XML
schema denition, if you want to use the OR operator for
paern-matching, use the | operator after the paern string.
If the | operator is used at the start of the regular expression,
Integration Server treats it as an empty string.
maxErrors

String Optional. Number of errors to be collected. Default value

is 1. When the number of errors found is equal to maxErrors ,
the validation processor stops validation and returns the
result. If maxErrors is set to -1, the validation processor
returns all errors.

ignoreContent

String Optional. Flag that species whether the validation

processor will validate content keys of the type String, String
List, or String Table.
Set to:
true to ignore content (that is, do not validate keys of these

types).

false to validate content. This is the default.

failIfInvalid

String Optional. Flag that indicates whether the service should

fail and throw an exception if the object is invalid. Set to:
true to indicate that the service should fail if the object is

invalid.

false to indicate that service should signal success and

return errors to the pipeline if object is invalid. This is the

default.
schemaDomain

String Optional. Schema domain in which the schema specied

by the XML namespaces resides. If schemaDomain is not
specied,Integration Server uses the default schema domain.
Note: This parameter only applies if object is a
com.wm.lang.xml.Document or com.wm.lang.xml.Node

Output Parameters
isValid

String Flag that indicates whether or not the validation was

successful. A value of:
true indicates that the validation was successful.

webMethods Integration Server Built-In Services Reference Version 9.6

654

Odd Header
Schema Folder

false indicates that the validation was unsuccessful.

errors

Document List Errors encountered during validation. Each

document will contain the following information:
Key

Description

pathName

String Location of the error in XQL.

errorCode

String Error code (for example, VV-001).

errorMessage

String Error message (for example,

Missing Object).

Usage Notes
When validating an IS document type or schema, Integration Server uses the Perl regular
expression compiler by default. If you need to change this behavior so that Integration
Server uses the Java regular expression compiler during validation, set the server
conguration parameter wa.core.datatype.usejavaregex to true. For information about
seing this conguration parameter, see webMethods Integration Server Administrators
Guide.
When validating against an IS document type, if the Allow null property is set to false for
a eld in the document type and the corresponding element in the instance document
carries the aribute xsi:nil, Integration Server throws the following error
[ISC.0082.9026] Undefined Object found.

When validating against an IS document type, if the Allow null property is set to false for
a eld in the document type and the corresponding element in the instance document
contains content or contains child elements, Integration Server throws the following
error:
[ISC.0082.9024] FieldName cannot have content or child elements since
xsi:nil is true.

When validating a com.wm.lang.xml.Document or com.wm.lang.xml.Nodeobject , Integration

Server searches the named schema domain for the specied schema. If the schema
cannot be found in the specied domain, Integration Server searches the default schema
domain. Note that Integration Server searches the schema domain for a schema, not an
individual component (element, aribute, complex type, etc) within the schema.
When validating XML, Integration Server uses the W3C recommendation XML Schema
Part 2: Datatypes. If you want to validate XML for illegal values, set ignoreContent to
false and the wa.core.validation.w3cConformant conguration parameter to true.
For information about seing this conguration parameter, see webMethods Integration
Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

655

Even Header
Schema Folder

The pub.schema:validate service cannot be used to validate a node produced by the

enhanced XML parser.

pub.schema:validatePipeline
WmPublic. Validates the pipeline against a document type.
Input Parameters
conformsTo

String Fully qualied name of the document type that you

want to validate the pipeline against.

maxErrors

String Optional. Number of errors to be collected. Default value

is 1. When the number of errors found is equal to maxErrors ,
the validation processor stops validation and returns the
result. If maxErrors is set to -1, the validation processor
returns all errors.

ignoreContent

String Optional. Flag that species whether the validation

processor will validate content keys of the type String, String
List, or String Table. Set to:
true to ignore content (that is, do not validate keys of these

types).

false to validate content. This is the default.

failIfInvalid

String Optional. Flag that indicates whether the service should

fail and throw an exception if the object is invalid. Set to:
true to indicate that service should fail if object is invalid.
false to indicate that service should simply signal success

and return errors to the pipeline if object is invalid. This is the

default.
Output Parameters
isValid

String Flag that indicates whether or not the validation was

successful. A value of:
true indicates that the validation was successful.
false indicates that the validation was unsuccessful.

webMethods Integration Server Built-In Services Reference Version 9.6

656

Odd Header
Schema Folder

errors

Document List Errors encountered during validation. Each

document will contain the following information:
Key

Description

pathName

String Location of the error in XQL.

errorCode

String Error code (for example, VV-001).

errorMessage

String Error message (for example,

Missing Object).

pub.schema.w3c
WmPublic. This folder contains denitions for XML Schemas as dened in the W3C
specication XML Schema Part 2: Datatypes.
For more information about schemas and datatypes, see webMethods Service Development
Help.

pub.schema.w3c:datatypes
WmPublic. A schema containing the simple type names for built-in schemas.

pub.schema.w3c:structures
WmPublic. A schema containing the structural components for XML schema denitions.

pub.schema.w3c:xml
WmPublic. A schema containing the XML namespace components, such as xml:lang and
xml:space, as dened in the W3C specications Namespaces in XML and Extensible Markup
Language (XML) 1.0.

pub.schema.w3c:xsi
WmPublic. A schema containing the XML Schema instance components, such as xsi:nil,
xsi:noNamespaceSchemaLocation, xsi:schemaLocation, and xsi:type, as dened in the
W3C XML Schema recommendation Part 1: Structures.

webMethods Integration Server Built-In Services Reference Version 9.6

657

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

658

Odd Header
Security Folder

29 Security Folder
About the Security Elements .....................................................................................................

660

Summary of Elements in this Folder .........................................................................................

661

webMethods Integration Server Built-In Services Reference Version 9.6

659

Even Header
Security Folder

You use the elements in the security folder to control which client certicates are sent to
other services and digitally sign data and process digital signatures. You can also use the
elements to store and retrieve outbound passwords to access secure resources.

About the Security Elements

Use the elements in the security folder to:
Control which client certicates are sent to other services.
Digitally sign data.
Process digital signatures.
Store and retrieve outbound passwords to access secure resources.
Manage Integration Server keystores and truststores.
Secure XML documents.
The services pub.security.keystore:setKeyAndChain, pub.security:setKeyAndChainFromBytes, and
pub.security:clearKeyAndChain are used to control which client certicate the webMethods
Integration Server presents to remote servers. You need to use these services to switch
between certicates and certicate chains if you are not using aliases for remote servers.
For more information about aliases for remote servers, see webMethods Integration Server
Administrators Guide.
The pub.security.outboundPasswords services support the use of encrypted outbound
passwords to access secure resources. You may wish to have a ow service access
a secure resource such as a remote Integration Server, proxy server, or database.
The service would need to provide a valid password to access the resource. The
pub.security.outboundPasswords services allow a ow service to store passwords in
and retrieve passwords from the Integration Server's outbound password store.
The outbound password store is an encrypted store of passwords managed by the
Integration Server. For more information about the outbound password store, see
webMethods Integration Server Administrators Guide.
The pub.security.keystore services allow you to congure Integration Server SSL through
access to its keys and associated certicates. These keys and certicates are now stored
securely in industry-standard keystore and truststore les. For more information
about Integration Server keystores and truststores, see webMethods Integration Server
Administrators Guide .
The pub.security.xml services are based on the Apache Security APIs. These services
support encryption and digital signing of outbound XML documents from Integration
Server, and decryption and signature verication of inbound XML from partner
applications. The services provide the most commonly-used XML security options,
including:
Signing/encrypting the entire XML document or the content of specic nodes
Selection of the signing and encryption algorithms

webMethods Integration Server Built-In Services Reference Version 9.6

660

Odd Header
Security Folder

Use of enveloping and enveloped signatures

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.security:clearKeyAndChain

WmPublic. Clears the set key and

certicate chain and reverts back to
the default key and certicate chain
for the subsequent set of invoked
services.

pub.security:setKeyAndChain

WmPublic. Deprecated - Replaced by

pub.security.keystore:setKeyAndChain.

pub.security:setKeyAndChainFromBytes

WmPublic. Associates a key and

certicate chain with the subsequent
set of invoked services. Use this
service to associate a key and
certicate chain that is dierent from
the default seings, and if your key
and certicate information is located
in byte arrays (rather than les).

pub.security.enterpriseGateway:alertSpec

WmPublic. Specication for ow

services used to send alerts about
violations of webMethods Enterprise
Gateway rules.

pub.security.keystore:getCertificate

WmPublic. Returns the trusted

certicate, stored in a truststore, that
corresponds to the certicate's alias.

pub.security.keystore:getKeyAndChain

WmPublic. Returns a private key and

its associated certicate chain from a
designated keystore.

pub.security.keystore:getTrustedCertificates

WmPublic. Returns the trusted

certicates located in a specied
truststore.

webMethods Integration Server Built-In Services Reference Version 9.6

661

Even Header
Security Folder

Element

Package and Description

pub.security.keystore:setKeyAndChain

WmPublic. Associates a key and

certicate chain with the subsequent
set of invoked services. Use this
service to associate a key and
certicate chain that is dierent from
the default seings, and if your key
and certicate information is stored in
a keystore le.

pub.security.keystore.pkcs7:sign

WmPublic. Creates a PKCS7 signed

Data object.

pub.security.outboundPasswords:setPassword

WmPublic. Stores a key and password

in the password store.

pub.security.outboundPasswords:getPassword

WmPublic. Retrieves a password from

the password store for a given key.

pub.security.outboundPasswords:listKeys

WmPublic. Lists the keys in the

password store.

pub.security.outboundPasswords:removePassword

WmPublic. Removes a password from

the password store for a given key.

pub.security.outboundPasswords:updatePassword

WmPublic. Changes the password

value for a key already in the
password store.

pub.security.pkcs7:sign

WmPublic. Creates a PKCS7

SignedData object.

pub.security.pkcs7:verify

WmPublic. Processes a digital

signature to guarantee that the data
associated with the signature has not
been modied.

pub.security.util:createMessageDigest

WmPublic. Generates a message

digest for a given message.

pub.security.util:getCertificateInfo

WmPublic. Retrieves information

such as serial number, issuer,

webMethods Integration Server Built-In Services Reference Version 9.6

662

Odd Header
Security Folder

Element

Package and Description

and expiration date from a digital
certicate.

pub.security.util:loadPKCS7CertChain

WmPublic. Converts a certicate chain

that is in PKCS #7 format to a list of
byte arrays.

pub.security.util:createSecureString

WmPublic. Creates a WmSecureString

object from either a Java String, byte
array, or character array.

pub.security.util:convertSecureString

WmPublic. Returns a
WmSecureString in Java String, byte
array, or character array format.

pub.security.util:destroySecureString

WmPublic. Destroys a
WmSecureString such that it no longer
resides in memory and is removed
from the pipeline.

pub.security.xml:decryptXML

WmPublic. Decrypts the encrypted

XML, and returns the XML as either a
string or stream object.

pub.security.xml:encryptXML

WmPublic. Encrypt an XML

document or node in an XML
document.

pub.security.xml:signXML

WmPublic. Digitally sign an outgoing

XML node or document.

pub.security.xml:verifyXML

WmPublic. Veries a signed XML

document, or node in an XML
document, and returns information
about the success or failure of the
verication.

pub.security:clearKeyAndChain
WmPublic. Clears the set key and certicate chain and reverts back to the default key
and certicate chain for the subsequent set of invoked services.

webMethods Integration Server Built-In Services Reference Version 9.6

663

Even Header
Security Folder

Input Parameters
None.
Output Parameters
None.
Usage Notes
The following scenario describes a situation in which you would use the
pub.security.keystore:setKeyAndChain and pub.security:clearKeyAndChain services.
Company A has a webMethods Integration Server with one certicate chain. Company
A wants to start trading with two new companies: Company B and Company C. Due
to explicit business decisions, both Company B and Company C require that secure
requests to their servers use certicates issued by their company's certicate authority.
Company A now has three certicate sets that it must manage: one for connections to
B, one for connections to C, and one for all other requests. Below is a high-level process
ow of what Company A would do if documents needed to be forwarded to companies
B, C, and D (some arbitrary partner without the stringent security).
Assume all network communication is done using HTTPS. Documents are sent to the
companies in the following order: Company D, Company B, Company C, Company D.
All data transfers make use of the pub.client:http service.
1. Invoke pub.client:http to send data to Company D.
2. Invoke pub.security.keystore:setKeyAndChain using the key and certicate chain for
Company B.
3. Invoke pub.client:http to send data to Company B.
4. Invoke pub.security.keystore:setKeyAndChain using the key and certicate chain for
Company C.
5. Invoke pub.client:http to send data to Company C.
6. Invoke pub.security:clearKeyAndChain to revert back to the default key and certicate
chain for Company A's server.
7. Invoke pub.client:http to send data to Company D.
See Also
pub.security.keystore:setKeyAndChain

pub.security:setKeyAndChain
WmPublic. Deprecated - Replaced by pub.security.keystore:setKeyAndChain.

webMethods Integration Server Built-In Services Reference Version 9.6

664

Odd Header
Security Folder

Associates a key and certicate chain with the subsequent set of invoked services. Use
this service to associate a key and certicate chain that is dierent from the default
seings, and if your key and certicate information is located in les (rather than byte
arrays).
Input Parameters
privKeyFile

String Absolute (for example, D:\certs\cert1.der) or

relative path of the le containing the private key. A
relative path is the path relative to the directory from
which the Integration Server has been started (for example,
Integration Server_directory\instances\instance_name \cong
\certs\cert1.der).

certFiles

String List of le names containing the certicates that comprise

the certicate chain. The list should start with the user's
certicate followed by (in order) intermediate certicates and
the root CA certicate.
Absolute or relative paths of the les can be specied.

Output Parameters
None.

pub.security:setKeyAndChainFromBytes
WmPublic. Associates a key and certicate chain with the subsequent set of invoked
services. Use this service to associate a key and certicate chain that is dierent from
the default seings, and if your key and certicate information is located in byte arrays
(rather than les).
Input Parameters
provoke

Object A byte array containing the client's private key.

certs

Object List List of byte arrays containing the client's certicate

chain. The list should start with the user's certicate followed
by (in sequence) intermediate certicates and the root CA
certicate.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

665

Even Header
Security Folder

Usage Notes
To enable this service to work properly if you use the FTPS protocol, you must set the
secure parameter to True in the pub.client:http and pub.client.ftp:login services.
You can use pub.security:clearKeyAndChain with
pub.security:setKeyAndChainFromBytes. See the Usage Notes for
pub.security:clearKeyAndChain for more information about using the
pub.security:setKeyAndChainFromBytes service.

pub.security.enterpriseGateway:alertSpec
WmPublic. Specication for ow services used to send alerts about violations of
webMethods Enterprise Gateway rules.
Use this specication as the signature of the ow service that Integration Server invokes
when a request violates an Enterprise Gateway rule. For more information about
webMethods Enterprise Gateway, see webMethods Integration Server Administrators Guide.
Input Parameters
ruleName

String The Enterprise Gateway rule that the request violates.

alertInfo

Document List Information for Enterprise Gateway alert

notication.
Key

Description

alertAction

String The action that the Integration

Server functioning as the Enterprise
Gateway Server takes when a request
violates an Enterprise Gateway rule.
The action will have one of these
values:
DENY if the server denies the request

and issues alerts as congured.

ALERT if the server allows the request

and issues alerts as congured.

requestType

String The specic request type to

which the server applies the Enterprise
Gateway rule. The values are:
ALL if the rule applies to all requests.

webMethods Integration Server Built-In Services Reference Version 9.6

666

Odd Header
Security Folder

SOAP if the rule applies to SOAP

requests only.

REST if the rule applies to REST

requests only.

INVOKE if the rule applies to INVOKE

requests only.
lterName

String The lter that the request

satises. The values are:
DoSFilter if the request satises the

Denial of Service seings specied

for Enterprise Gateway rules.

MsgSizeLimitFilter if the request

satises the Message Size Limit lter

in the rule.
OAuthFilter if the request satises

the OAuth lter in the rule.

mobileAppProtectionFilter

if the request satises the Mobile

Application Protection lter in the
rule.
None if the request violates a rule that

has no lters.
message

String The details about the lter

condition that the request satises.

requestUser

String The user ID that sent the

request that violates the Enterprise
Gateway rule. This eld is empty
if authentication is disabled on
Enterprise Gateway Server. For more
information about authentication
on Enterprise Gateway Server,
see webMethods Integration Server
Administrators Guide.

requestHost

String The host name or IP address of

the client that sent the request.

requestTime

String Date and time at which the

request reached Enterprise Gateway
Server. This parameter is in the format

webMethods Integration Server Built-In Services Reference Version 9.6

667

Even Header
Security Folder

yyyy-MM-dd HH:mm:ss z, where z

indicates the time zone.

resourcePath

String The path of the resource to be

accessed by the request.

serverHost

String The host name or IP address of

the Enterprise Gateway Server that
received the client request.

serverPort

String The number of the Enterprise

Gateway Server port that received the
client request.

Output Parameters
None.

pub.security.keystore:getCertificate
WmPublic. Returns the trusted certicate, stored in a truststore, that corresponds to the
certicate's alias.
Input Parameters
trustStoreAlias

String Alias for the truststore containing the certicate.

certAlias

String Alias identifying a particular trusted certicate within a

truststore.

Output Parameters
certicate

byte[ ] A byte array containing the trusted certicate.

Usage Notes
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide

webMethods Integration Server Built-In Services Reference Version 9.6

668

Odd Header
Security Folder

pub.security.keystore:getKeyAndChain
WmPublic. Returns a private key and its associated certicate chain from a designated
keystore.
Input Parameters
keyStoreAlias

String Alias for the keystore that contains the private key of
interest and its certicate.

keyAlias

String Alias for the private key stored in the specied keystore.

Output Parameters
privateKey

java.security.PrivateKey Object representing the private key.

certChain

byte[ ] [ ] List of byte arrays representing the certicate chain

associated with the private key.

Usage Notes
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide.

pub.security.keystore:getTrustedCertificates
WmPublic. Returns the trusted certicates located in a specied truststore.
Input Parameters
trustStoreAlias

String Name of the truststore alias.

Output Parameters
certicates

byte[ ] [ ] Trusted certicates, as a list of byte arrays.

Usage Notes
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

669

Even Header
Security Folder

pub.security.keystore:setKeyAndChain
WmPublic. Associates a key and certicate chain with the subsequent set of invoked
services. Use this service to associate a key and certicate chain that is dierent from the
default seings, and if your key and certicate information is stored in a keystore le.
Input Parameters
keyStoreAlias

String Name of the keystore alias.

keyAlias

String Alias of the private key located in the keystore.

Output Parameters
None.
Usage Notes
This service replaces pub.security:setKeyAndChain, which is deprecated.
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide
See Also
pub.security:clearKeyAndChain

pub.security.keystore.pkcs7:sign
WmPublic. Creates a PKCS7 signed Data object.
Input Parameters
signerInfo

Document List Information about a single signer of the signed

data object. Each signerInfo requires either a certicate chain
and a private key or a key alias that references them.
Key

Description

keyStoreAlias

String Name of the keystore alias.

keyAlias

String Alias of the private key.

webMethods Integration Server Built-In Services Reference Version 9.6

670

Odd Header
Security Folder

hashAlgorithm

String The algorithm to use when

computing the digest of the provided
data. Specify:
MD5 (the default)
SHA-1
SHA-256
SHA-384
SHA-512

data

byte[ ] Data to be digitally signed.

detachedSignature

String Flag specifying whether to generate a detached

signature. A detached signature does not include the data that
was signed. Set to:
true to generate a detached signature.
false to generate an implicit signature (one that includes the

signed data). This is the default.

Output Parameters
signature

byte[ ] Signature generated from the supplied data. This is

a DER-encoded representation of the SignedData object as
specied in PKCS#7.

Usage Notes
This service supersedes pub.security.pkcs7:sign, which is deprecated.
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide.

pub.security.outboundPasswords:setPassword
WmPublic. Stores a key and password in the password store.
Input Parameters
key

String Key to be associated with the password entry.

value

WmSecureString Password to be stored.

webMethods Integration Server Built-In Services Reference Version 9.6

671

Even Header
Security Folder

isInternal

String "true" if this should be saved as an internal password;

"false" if it should be saved as a public password. Default is
"false". (See "Internal and Public Passwords" on page 672
for more information.)

Output Parameters
result

String "true" if password was successfully stored; "false"

otherwise.

message

String "successful" or reason for failure.

Usage Notes
This is the basic process a ow service should follow to store an outbound password:
1. Call pub.security.util:createSecureString to create a WmSecureString object containing the
password to be stored.
For security reasons, the ow service should be run manually requiring an
authorized person to type the password to be stored. This will eliminate the need to
save the password on disk in an unencrypted format.
2. Call pub.security.outboundPasswords:setPassword to save the password in encrypted form
in the outbound password store.
The pub.security.outboundPasswords:setPassword service requires a key to be supplied
which is basically a key to the password. This key must be saved in some way; any
ow service wishing to use the password to access a secure resource will need to
supply the key to retrieve the password from the outbound password store.
3. Once the password is successfully stored, call pub.security.util:destroySecureString to
remove the password from memory.

Internal and Public Passwords

Internal passwords are passwords for use by the Integration Server itself to access secure
resources (e.g., remote Integration Servers, JDBC connection pools, LDAP servers,
etc.). Internal passwords are managed using the Integration Server Administrator and
are stored in the outbound password store. Flow services are also allowed to store
passwords in the outbound password store. However, by default, passwords stored by
a ow service are considered "public," as opposed to internal. This distinction allows
ow services to use the outbound password store as a secure mechanism for storing and
retrieving passwords, but protects the Integration Server's internal passwords.
When calling any of the pub.security.outboundPasswords services (i.e. setPassword, getPassword,
listKeys, removePassword, and updatePassword) the isInternal input parameter indicates
whether the service is working with internal or public passwords. Note that even if

webMethods Integration Server Built-In Services Reference Version 9.6

672

Odd Header
Security Folder

this parameter is set to "true", you cannot access internal passwords if the Integration
Server is congured to deny access to internal passwords. Access to internal passwords
is controlled by the wa.security.ope.AllowInternalPasswordAccess conguration
parameter on the Integration Server; for more information see webMethods Integration
Server Administrators Guide.

pub.security.outboundPasswords:getPassword
WmPublic. Retrieves a password from the password store for a given key.
Input Parameters
key

String Key of the password entry to be retrieved.

isInternal

String "true" if this is an internal password; "false" if it is public.

By default, this is "false". If you specify incorrectly whether the
password is internal or public, the retrieve operation will fail.
(For more information about internal and public passwords,
see "Internal and Public Passwords" on page 672.)

Output Parameters
value

WmSecureString Value of the retrieved password.

result

String "true" if the password value was successfully retrieved;

"false" otherwise.

message

String "successful" or reason for failure.

Usage Notes
This is the basic process a ow service should follow to retrieve an outbound password:
1. Call pub.security.outboundPasswords:getPassword with the key to the password to be
retrieved.
If the key is unknown, you can call pub.security.outboundPasswords:listKeys to retrieve a
list of keys currently in the outbound password store.
The pub.security.outboundPasswords:getPassword service returns a WmSecureString object
containing the retrieved password.
2. Call pub.security.util:convertSecureString to convert the password to a usable format.
The password can then be passed to the authenticating mechanism of the secure
resource.

webMethods Integration Server Built-In Services Reference Version 9.6

673

Even Header
Security Folder

3. When done accessing the secure resource, call pub.security.util:destroySecureString to

remove the password from memory.

pub.security.outboundPasswords:listKeys
WmPublic. Lists the keys in the password store.
Input Parameters
isInternal

String "true" if you want keys for internal passwords; "false" if

you want keys for public passwords. By default this is "false".
(For more information about internal and public passwords,
see "Internal and Public Passwords" on page 672.)

Output Parameters
key

IData List of keys in the password store.

result

String "true" if the list of keys was successfully retrieved; "false"

otherwise.

pub.security.outboundPasswords:removePassword
WmPublic. Removes a password from the password store for a given key.
Input Parameters
key

String Key of the password to be removed.

isInternal

String "true" if this is an internal password; "false" if it is public.

By default, this is "false". If you specify incorrectly whether the
password is internal or public, the remove operation will fail.
(For more information about internal and public passwords,
see "Internal and Public Passwords" on page 672.)

Output Parameters
result

String "true" if the password was successfully removed; "false"

otherwise.

webMethods Integration Server Built-In Services Reference Version 9.6

674

Odd Header
Security Folder

message

String "successful" or reason for failure.

pub.security.outboundPasswords:updatePassword
WmPublic. Changes the password value for a key already in the password store.
Input Parameters
key

String Key of the password to be updated.

newPassword

WmSecureString New password value for the key.

isInternal

String "true" if this is an internal password; "false" if it is public.

By default, this is "false". If you specify incorrectly whether the
password is internal or public, the update operation will fail.
(For more information about internal and public passwords,
see "Internal and Public Passwords" on page 672.)

Output Parameters
result

String "true" if the password value was successfully changed;

"false" otherwise.

message

String "successful" or reason for failure.

pub.security.pkcs7:sign
WmPublic. Deprecated - Replaced by pub.security.keystore.pkcs7:sign.
Creates a PKCS7 SignedData object.
This service enables multiple entities to sign the specied data. Each signerInfo block
contained in the resulting signature contains two authenticated aributes: the content
type and a timestamp.
Input Parameters
signerInfo

Document List Information about a single signer of the signed

data object. Each signerInfo requires either a certicate chain
and a private key or a key alias that references them.

webMethods Integration Server Built-In Services Reference Version 9.6

675

Even Header
Security Folder

Key

Description

certChain

java.security.cert.X509Certificate[ ] or
byte[ ][ ] Certicate chain of the signer.
The subject that is performing the
signature should be the rst certicate
in this chain, while the root Certifying
Authority should be the last. The
key provided should correspond to
the public key contained in the rst
certicate of the chain.

key

java.security.PrivateKey or byte[ ] Private

key that will be used to digitally
sign the data. The private key can
be any asymmetric encryption key
that is supported by the webMethods
Integration Server (for example, DSA or
RSA).

keyAlias

String Alias of the certicate chain and

private key in the key store. This key is
not currently used.

hashAlgorithm

String The algorithm to use when

computing the digest of the provided
data (SHA-1 or MD5). The default value
is MD5.

data

byte[ ] Data to be digitally signed.

detachedSignature

String Flag specifying whether to generate a detached

signature. A detached signature does not include the data that
was signed. Set to:
true to generate a detached signature.
false to generate an implicit signature (one that includes the

signed data). This is the default.

Output Parameters
signature

byte[ ] Signature generated from the supplied data. This is

a DER-encoded representation of the SignedData object as
specied in PKCS#7.

webMethods Integration Server Built-In Services Reference Version 9.6

676

Odd Header
Security Folder

Usage Notes
This service is superseded by pub.security.keystore.pkcs7:sign.

pub.security.pkcs7:verify
WmPublic. Processes a digital signature to guarantee that the data associated with the
signature has not been modied.
Input Parameters
signature

byte[ ] Signature to use to determine whether the signed data is

intact (a DER-encoded representation of the SignedData object
as specied in PKCS#7). If you are processing a detached
signature, pass the signature in signature . If you are processing
an implicit signature, pass the entire signed message in
signature .

data

byte[ ] Optional. The data that was signed. If you are

processing a detached signature, you must supply data . If you
are processing an implicitly signed message, you do not need
to supply data because both the message and the signature
reside in signature .

detachedSignature

String Optional. Flag indicating whether the message has a

detached signature. Set to:
true when the message has a detached signature.
false when the message has an implicit signature. This is the

default.
signerCertChain

byte[ ][ ] Optional. Certicate chains of the parties that signed

the message.
Note: If the signers included the certicate chain with the digital
signature, you do not need to supply signerCertChain .

Output Parameters
content

byte[ ] Conditional. The data (for example, the document that

was originally signed) extracted from an implicit signature. If
you are verifying a detached signature, content is not returned.

webMethods Integration Server Built-In Services Reference Version 9.6

677

Even Header
Security Folder

Note: The extracted data is returned in content even if signature

verication fails.
signerInfo

Document List Information about the signers. Each document

in the list provides the following information about a single
signer:
Key

Description

certChain

java.security.cert.X509Certificate[ ]
Certicate chain of the signer. The
chain will appear in hierarchical
order, starting with the signer's X.509
certicate in element 0.

timeStamp

java.util.Date Time at which the signer

signed the data.

trusted

String Flag indicating whether the

certicate chain presented by the signer
is trusted. A value of:
true indicates that the chain is trusted.

false indicates that the chain is not

trusted.
status

String Flag indicating whether the

signatures were successfully veried.
If successful, status contains verified.
If the signatures were not successfully
veried, status contains an error
message.

pub.security.util:createMessageDigest
WmPublic. Generates a message digest for a given message.
Input Parameters
algorithm

String Name of the algorithm that you want to use to compute

the message digest. Must be one of the following: MD5,SHA-1,
SHA-256, SHA-384, or SHA-512.

webMethods Integration Server Built-In Services Reference Version 9.6

678

Odd Header
Security Folder

input

byte[ ] Message for which you want the digest generated.

Output Parameters
output

byte[ ] Computed digest.

pub.security.util:getCertificateInfo
WmPublic. Retrieves information such as serial number, issuer, and expiration date
from a digital certicate.
Input Parameters
certicate

byte[] java.security.cert.X509Certificate The certicate whose

information you want to retrieve.

Output Parameters
info

Document Information from the certicate.

Key

Description

version

java.lang.Number X509 certicate version

number.

serialNumber

String Serial number of the certicate.

signature

String Signature algorithm used by the

issuer to sign this certicate.

issuer

Document Detailed information about the

CA that signed the certicate, such as
name, location, and e-mail address.

validity

Document The time period over which

the certicate is valid.
Key

Description

notBefore

String First date

on which this

webMethods Integration Server Built-In Services Reference Version 9.6

679

Even Header
Security Folder

certicate is valid
(for example,
3/15/00 3:36PM).
notAfter

String Last date

on which this
certicate is valid
(for example,
3/15/00 3:36PM).

subject

Document Detailed information about the

owner of the certicate, such as name,
location, and mail address.

subjectPublicKey
Algorithm

String Encryption algorithm with which

the certicate's key is designed to be
used (for example, RSA or DSA).

pub.security.util:loadPKCS7CertChain
WmPublic. Converts a certicate chain that is in PKCS #7 format to a list of byte arrays.
Input Parameters
certicateChain

byte[ ] The certicate chain in PKCS #7 format.

Output Parameters
certicates

byte[ ] [ ] List of byte arrays in which each byte[ ] in the list

contains a certicate from certicateChain .

pub.security.util:createSecureString
WmPublic. Creates a WmSecureString object from either a Java String, byte array, or
character array.
WmSecureString is a mutable alternative to Java String. It allows the characters in the
string to be explicitly removed from memory. Any password you wish to store in the
Integration Server's outbound password store must be converted to a WmSecureString.

webMethods Integration Server Built-In Services Reference Version 9.6

680

Odd Header
Security Folder

Input Parameters
string

String Java String to made into a WmSecureString.

bytes

byte[ ] Byte array to be made into a WmSecureString.

chars

char[ ] Character array to be made into a WmSecureString.

encoding

String If a byte array is supplied as an input parameter,

encoding species the Java encoding of the byte array. This
may be any encoding supported by Java String. By default,
if no encoding is specied, then the default JVM encoding is
used.

Output Parameters
secureString

WmSecureString WmSecureString created from the supplied

input parameters.

Usage Notes
Only one of the input parameters (i.e. string , bytes , or chars ) may be specied. If more
than one is specied, an exception will be thrown. An exception is also thrown if none of
these is specied.

pub.security.util:convertSecureString
WmPublic. Returns a WmSecureString in Java String, byte array, or character array
format.
Input Parameters
secureString

WmSecureString WmSecureString to be converted.

returnAs

String Format into which the WmSecureString is to be

converted. Valid options are byte[], char[], and Java String.
If a value for this parameter is not specied, the default is to
convert the WmSecureString to a String.

webMethods Integration Server Built-In Services Reference Version 9.6

681

Even Header
Security Folder

Output Parameters
string

String The WmSecureString converted to a Java String.

bytes

byte[ ] The WmSecureString converted to a native Java byte

array.

chars

char[ ] The WmSecureString converted to a native Java

character array.

pub.security.util:destroySecureString
WmPublic. Destroys a WmSecureString such that it no longer resides in memory and is
removed from the pipeline.
Input Parameters
secureString

WmSecureString WmSecureString to be destroyed.

Output Parameters
None.

pub.security.xml:decryptXML
WmPublic. Decrypts the encrypted XML, and returns the XML as either a string or
stream object.
Input Parameters
xmldata

String Optional. Encrypted XML that needs to be decrypted as

plain text.

xmlStream

InputStream Optional. Encrypted XML in the form of an input

stream.
Note: If both xmldata and xmlStream are provided, xmlStream
takes precedence; Integration Server uses the xmlStream value
and returns only decryptedXMLStream .

webMethods Integration Server Built-In Services Reference Version 9.6

682

Odd Header
Security Folder

keyStoreAlias

String Optional. Alias of the keystore that contains the private

key used for decryption.

keyAlias

String Optional. Alias of the private key, contained in the

keystore specied by the keyStoreAlias parameter, that is used
for decryption.

encoding

String Optional. Species the encoding to use if the encoding

cannot be extracted from the XML. If encoding is not
specied in the XML document or in the encoding parameter,
Integration Server uses UTF-8.
The encoding value must be a valid IANA encoding.

Output Parameters
decryptedXMLData

String Conditional. Decrypted XML data. decryptedXMLData

is returned when the input parameter xmldata is provided.

decryptedXMLStream

Object Conditional. A decrypted XML OutputStream object.

decryptedXMLStream is returned when the input parameter
xmlStream is provided.

Usage Notes
There are several prerequisites to using pub.security.xml:decryptXML:
Certicates must be congured for Integration Server and the client with which it is
exchanging secure XML.
The sending, encrypting client must have access to Integration Server's public key
before the document exchange can occur.
Integration Server stores its certicates in keystores and truststores. You must
congure a keystore and truststore for Integration Server before using the XML
encryption services.
You access the public and private keys for Integration Server through aliases. For
information about Integration Server keystores and truststores, refer to webMethods
Integration Server Administrators Guide.
The pub.security.xml:decryptXML service works as follows:
1. The external system sends the XML document encrypted with the Integration
Server's public key.
2. Integration Server receives the document and passes it to the XML service.
3. Integration Server uses the private key member of the key pair to decrypt the XML.

webMethods Integration Server Built-In Services Reference Version 9.6

683

Even Header
Security Folder

4. The decrypted XML is returned from the service.

If both xmldata and xmlStream are provided, xmlStream takes precedence; Integration
Server uses the xmlStream value and returns only decryptedXMLStream .
keyAlias and keyStoreAlias should either both be provided or both be absent from the
input. If no value is provided for these parameters, Integration Server uses the private
key/certicate specied for the Decryption Key. If no value is specied for Decryption
Key, Integration Server uses the SSL Key.
For information about conguring the Decryption Key and SSL Key keystore aliases,
refer to webMethods Integration Server Administrators Guide.

pub.security.xml:encryptXML
WmPublic. Encrypt an XML document or node in an XML document.
Input Parameters
xmldata

String Optional. The XML to be encrypted.

xmlStream

InputStream Optional. Input stream to the XML that needs to

be encrypted.
Note: If both xmldata and xmlStream are provided, xmlStream
takes precedence.

nodeSelectors

String List XPaths to the node to be encrypted. If the value for

this parameter is left empty, no XML will be encrypted.

nsDecls

Document Optional. Mapping of the namespace prexes to

the namespace URIs. The rst column contains the prexes
and the second column contains the corresponding URIs.

recipientID

String Optional. Name of the client to which the XML will

be sent. The user name and certicate must be congured
with Integration Server certicate mapping. The client name
entry is mapped to a valid X.509 certicate, and both are
stored in Integration Server.
For information about Integration Server certicate
mapping, see webMethods Integration Server Administrators
Guide.

recipientCert

Byte[] Optional. The certicate containing the public key that

will be used to encrypt the XML. If the input parameters

webMethods Integration Server Built-In Services Reference Version 9.6

684

Odd Header
Security Folder

recipientCert and recipientID are both provided, recipientCert

is used.
contentOnly

Boolean Optional. Indicates whether the XML tags

surrounding the content will be encrypted along with the
content. Set to:
true to encrypt only the content.
false to encrypt both the tags and the content. This is the
default.

algorithm

String Optional. The symmetric key algorithm to use for

encryption. Set to:
tripledes-cbc for the algorithm at hp://
www.w3.org/2001/04/xmlenc#tripledes-cbc

This is the default.

aes256-cbc for the algorithm at hp://

www.w3.org/2001/04/xmlenc#aes256-cbc
aes192-cbc for the algorithm at hp://
www.w3.org/2001/04/xmlenc#aes192-cbc
aes128-cbc for the algorithm at hp://
www.w3.org/2001/04/xmlenc#aes128-cbc

Note: If you are using aes256-cbc or aes192-cbc with

JVM 1.6, make sure the unlimited policy jar les have been
installed.
encryptedKeyAlgorithm

String Optional. The symmetric key that is randomly

generated, and then encrypted with the receiver's public
key. This encryption uses an asymmetric algorithm if public/
private key pairs are being used. Set to:
rsa-1_5 for the algorithm at hp://www.w3.org/2001/04/
xmlenc#rsa-1_5

This is the default.

rsa-oaep-mgf1p for the algorithm at hp://
www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

encoding

String Optional. Species the encoding to use if the

encoding cannot be extracted from the XML. If encoding
is not specied in the XML document or in the encoding
parameter, Integration Server uses UTF-8.
The encoding value must be a valid IANA encoding.

webMethods Integration Server Built-In Services Reference Version 9.6

685

Even Header
Security Folder

Output Parameters
encryptedXMLData

String Conditional. Encrypted XML data. encryptedXMLData

is returned when the input parameter xmldata is provided.

encryptedXMLStream

OutputStream Conditional. Encrypted XML in the form of an

OutputSream. encryptedXMLStream is returned when the
input parameter xmlStream is provided.

Usage Notes
If both xmldata and xmlStream are provided, xmlStream takes precedence.
There are several prerequisites to using the pub.security.xml:encryptXML service:
Certicates must be congured for Integration Server and the client with which it is
exchanging encrypted XML.
Before an encrypted XML document can be exchanged between Integration Server
and an external system, the external system must share its public key.
Prior to use of pub.security.xml:encryptXML, Integration Server must have access to the
partner's public key. Such access is possible through:
An Integration Server certicate mapping (for information, refer to webMethods
Integration Server Administrators Guide).
A copy of the partner's X.509 certicate that is available to Integration Server.
In pub.security.xml:encryptXML, the certicate/public key is specied through one of the
following input parameters: the client's name (through recipientID), or the public key of
the partner application (through recipientCert) .
Because encryption is a processing-intensive activity, it is recommended to only encrypt
the XML nodes requiring protection.
Signing and Encrypting the Same XML Document
You can use both encryption and signing in the same XML document.
If you sign and encrypt dierent XML elements in a document, you can run either
pub.security.xml:signXML or pub.security.xml:encryptXML rst.
Typically, if you sign and encrypt the same XML elements in a document,
you should sign the elements before encrypting them. That is, invoke
pub.security.xml:signXML before invoking pub.security.xml:encryptXML.

pub.security.xml:signXML
WmPublic. Digitally sign an outgoing XML node or document.

webMethods Integration Server Built-In Services Reference Version 9.6

686

Odd Header
Security Folder

Input Parameters
xmldata

String Optional. XML that needs to be signed.

xmlStream

InputStream Optional. Input stream containing the XML

that needs to be signed.
Note: If both xmldata and xmlStream are provided,
xmlStream takes precedence.

uri

String Optional. URI to the element to be signed.

In combination with the nodeSelectors parameter, the
uri identies the nodes to be signed.

noNamespace SchemaLocation String Optional. A URI that identies the location of the
XML schema denition that contains the ID aribute
specied in uri .
Provide a noNamespaceSchemaLocation when specifying
an ID aribute for uri and the ID aribute resides in an
XML schema with no namespaces.
schemaLocations

Document Optional. Document (IData) containing

name-value pairs for the XML namespace and the
location of the XML schema denition that contains
element declarations, aribute declarations, and type
denitions for that namespace.
Provide a schemaLocation when specifying an ID
aribute for uri and the ID aribute resides in an XML
schema for a particular namespace.
For example,
XML namespace = hp://www.w3schools.com
XML schema denition location = le:C:/note.xsd

nodeSelectors

String List XPath notation that identies the nodes to be

signed. The locations of the XPaths are not absolute,
but relative, and work within the context of the node
(an XPath Axes).
Important: Do not use absolute location XPaths here.

nsDecls

Document Optional. Mapping of the namespace prexes

to the namespace URIs. The rst column contains

webMethods Integration Server Built-In Services Reference Version 9.6

687

Even Header
Security Folder

the prexes and the second column contains the

corresponding URIs.
isEnveloped

String Optional. Indicates whether the signature should

be enveloped or enveloping. Set to:
True to indicate the signature is enveloped. This is

the default.

False to indicate the signature is enveloping.

signatureNodeSelector

String Optional. XPath to the node where the signature

is entered. Applicable only for enveloped signatures. If
no value is provided, the signature is placed as a rst
child of the root node.

signatureAlgorithm

String Optional. Signature algorithm to use when

signing the XML node or document. Specify one of the
following or use the default value (rst algorithm):
SHA1 (default)
SHA256
SHA384
SHA512

digestAlgorithm

String Optional. Digest algorithm to use when signing

the XML node or document. Specify one of the
following or use the default value (rst algorithm):
SHA1 (default)
SHA256
SHA384
SHA512

canonicalizationAlgorithm

String Optional. Canonical algorithm used with the

XML. Specify one of the following or use the default
value (rst algorithm):
hp://www.w3.org/TR/2001/rec-xml-c14n-20010315
(default)
hp://www.w3.org/TR/2001/rec-xmlc14n-20010315#WithComments
hp://www.w3.org/2001/10/xml-exc-c14n#

webMethods Integration Server Built-In Services Reference Version 9.6

688

Odd Header
Security Folder

hp://www.w3.org/2001/10/xml-excc14n#WithComments
signatureId

String Optional. ID aribute for the signature node.

keyStoreAlias

String Optional. Name (alias) of the keystore that

contains the private key/certicate.

keyAlias

String Optional. Name (alias) of the private key,

contained in the keystore specied by the keyStoreAlias
parameter, that is used for signing.

includeCertChain

String Optional. Indicates whether the certicate chain

should be included in the signature. Set to:
True to include the certicate chain in the signature.
False to leave the certicate chain out of the

signature. This is the default.

certData

String Optional. Select the X509 certicate data that

should be entered into the signature's key information.
Note that the initials "SKI" in the last option stand for
"Subject Key Identier."
X509_CERTIFICATE (default)
X509_SUBJECT_NAME
X509_ISSUER_SERIAL
X509_SKI

idXmlObject

String Optional. Species the ID for the node that holds

the original XML that is signed. Applicable only for
enveloping signatures.

encoding

String Optional. Species the encoding to use if

the encoding cannot be extracted from the XML. If
encoding is not specied in the XML document or in
the encoding parameter, Integration Server uses UTF-8.
The encoding value must be a valid IANA encoding.

addSignatureAsLastElement

Boolean Optional. When isEnveloped is set to True, this

parameter indicates the position at which Integration
Server should add the signature element child to the
root. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

689

Even Header
Security Folder

True to add the signature element as the last child of

the root.

False to add the signature element as the rst child

of the root. This is the default.

Output Parameters
signedXMLData

String Conditional. Signed XML data. signedXMLData is

returned when xmlData is provided.

signedXMLStream

OutputStream Conditional. Signed XML in the form of an

OutputSream. signedXMLStream is returned when xmlStream
is provided.

Usage Notes
Before the signing/signature verication of XML can occur between Integration
Server and an external system, the Integration Servermust share the public key that
corresponds to the private key with which the document is signed. Integration Server
must share the public key with the external system that will be performing verication.
keyAlias and keyStoreAlias should either both be provided or both be absent from
the input. If no value is provided for these parameters, Integration Server uses the
private key/certicate specied for the Signing Key. If the Signing Key is not specied,
Integration Server uses the SSL Key.
For information about conguring the Signing Key and SSL Key keystore aliases using
the Security > Certificates screen in Integration Server Administrator, refer to webMethods
Integration Server Administrators Guide.
If both xmldata and xmlStream are provided, xmlStream takes precedence.
The uri and nodeSelectors parameters identify the nodes to be signed.
If uri is specied and nodeSelectors is not specied, Integration Server signs the entire
node identied by uri .
If uri and nodeSelectors are specied, Integration Server determines which nodes to sign
by locating the node specied by the uri and then applying the lter from nodeSelectors .
If uri is not specied and nodeSelectors is specied, Integration Server determines which
nodes to sign by applying the lter in nodeSelectors to the entire XML.
If neither uri nor nodeSelectors are specied, Integration Server signs the entire XML.
You can use the value of an ID aribute as the uri .
For example, #sampleID
Where sampleID is an ID aribute that functions as a unique identier for an element
in an XML schema denition. In this example, Integration Server will locate the node
webMethods Integration Server Built-In Services Reference Version 9.6

690

Odd Header
Security Folder

with the ID aribute "sampleID" and then apply the lter specied by nodeSelectors to
determine which nodes to sign.
Signature Types
As opposed to a detached signature, which is kept apart from the original document,
enveloping and enveloped signatures are tightly coupled with the original document.
An enveloping signature must be a parent node of the data being signed:
<!-- Example of Enveloping Signature --> <Signature>
<my_document>. . . </my_document> </Signature>

The following input parameters and values are applicable only to enveloping signatures:
isEnveloped. Specify a value of "false" for enveloping. If isEnveloped is set to false,
then:
If both uri and idXmlObject are null, Integration Server creates a dynamic unique
value for both uri and idXmlObject and signs the XML.
If idXmlObject is provided and uri is null, Integration Server creates a uri with a
value of #idXmlObject_value and signs the XML.
If both and uri and idXmlObject are provided and match the XML contract (for
example, uri ='#idXmlObject '), Integration Server signs the XML. If the uri and
idXmlObject parameters do not match the contract, Integration Server issues an
exception.
idXmlObject. Species the ID for the node that holds the original, signed XML.
An enveloped signature must be a child node of the data being signed:
<!-- Example of Enveloped Signature --> <my_document>
<Signature> . . . </Signature> </my_document>

The following parameters and values are applicable only to enveloped signatures:
isEnveloped. The default value of "true" species that the signature is enveloped.
signatureNodeSelector. XPath to the node where the signature is entered. If no value is
provided, the signature is placed as a rst child of the root node.
pub.security.xml:signXML does not support detached signatures.
Signing and Encrypting the Same XML Document
You can use both encryption and signing in the same XML document.
If you sign and encrypt dierent XML elements in a document, you can run either
pub.security.xml:signXML or pub.security.xml:encryptXML rst.
Typically, if you sign and encrypt the same XML elements in a document, you should
sign the elements before encrypting them. That is, invoke pub.security.xml:signXML
before invoking pub.security.xml:encryptXML.

webMethods Integration Server Built-In Services Reference Version 9.6

691

Even Header
Security Folder

pub.security.xml:verifyXML
WmPublic. Veries a signed XML document, or node in an XML document, and returns
information about the success or failure of the verication.
Input Parameters
xmldata

String Optional. Signed XML that needs to be veried.

xmlStream

InputStream Optional. Signed XML as an input stream that

needs to be veried.
Note: If both xmldata and xmlStream are provided, xmlStream
takes precedence.

signatureSelectors

String Array XPaths that are used to identify the signature; can
be any valid XPath. Following is an example:
//*[@ID="Sign001"]

nsDecls

Document Optional. Mapping of the namespace prexes to the

namespace URIs. The rst column contains the prexes and
the second column contains the corresponding URIs.

noNamespace
SchemaLocation

String Optional. Schema location for elements with no

namespace. This parameter is used to locate the schema that
denes elements without a namespace prex.

schemaLocations

Document Optional. Holds the schema locations against the

namespaces.

encoding

String Optional. Species the encoding to use if the encoding

cannot be extracted from the XML. If encoding is not
specied in the XML document or in the encoding parameter,
Integration Server uses UTF-8.
The encoding value must be a valid IANA encoding.

Output Parameters
verifcationResult

Boolean Indicates whether the signed XML is authentic

(true) or cannot be veried or shows signs of tampering
(false).

webMethods Integration Server Built-In Services Reference Version 9.6

692

Odd Header
Security Folder

failedSignatureSelector

String Conditional. In case of a verication failure (the

digests do not equate), indicates which signature selector
failed.

failureReason

String Conditional. This output parameter is populated

only in the case of a verication failure. Its value indicates
whether (1) the signature caused the failure, or (2) the
signature is from an untrusted certicate. Possible values
are:
SIGNATURE FAILED
CERTIFICATE NOT TRUSTED

certMap

Document List Conditional. For each XPath in

signatureSelector , certMap contains a document that
identies the XPath and the corresponding signing
certicate found at that XPath.
certMap is only returned if certicates were resolved for at
least one the XPaths specied in signatureSelector .
If Integration Server encounters a signature failure,
Integration Server does not resolve any subsequent XPaths.
certMap contains all of the XPaths and corresponding
certicates that Integration Server could resolve up to the
point of failure.

Usage Notes
If both xmldata and xmlStream are provided, xmlStream takes precedence.
Before pub.security.xml:verifyXML can verify a signature, the partner application's public key
must have been made available to Integration Server, either through:
Integration Server certicate mapping.
The partner application having sent a copy of its certicate to Integration Server.
For information on Integration Server certicate mapping, refer to webMethods Integration
Server Administrators Guide.
The pub.security.xml:verifyXML service works as follows:
1. Integration Server receives the signed XML document.
2. Integration Server extracts the public key from the partner application's certicate.
3. Integration Server uses the public key to verify the authenticity of the XML
document.

webMethods Integration Server Built-In Services Reference Version 9.6

693

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

694

Odd Header
SMIME Folder

30 SMIME Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

696

695

Even Header
SMIME Folder

You use the elements in the smime folder to create digitally signed and/or encrypted
MIME messages. You also use the services in this folder to process signed and encrypted
MIME messages that are passed into the pipeline.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.smime:createCertsOnlyData

WmPublic. Generates a PKCS #7

certs-only S/MIME entity from an
array of certicates.

pub.smime:createEncryptedData

WmPublic. Encrypts a MIME

message.

pub.smime:createSignedAndEncryptedData

WmPublic. Deprecated - Replaced by

pub.smime.keystore:createSignedAndEncryptedData.
Digitally signs a MIME message and
then encrypts it.

pub.smime:createSignedData

WmPublic. Deprecated - Replaced

by pub.smime.keystore:createSignedData.
Digitally signs a MIME message.

pub.smime:processCertsOnlyData

WmPublic. Extracts the certicates

from a PKCS #7 certs-only S/MIME
entity.

pub.smime:processEncryptedData

WmPublic. Deprecated - Replaced by

pub.smime.keystore:processEncryptedData.

pub.smime:processSignedData

WmPublic. Veries the signature

from a signed S/MIME entity and
extracts the message from it.

pub.smime.keystore:createSignedAndEncryptedData

WmPublic. Digitally signs and

encrypts a MIME message.

pub.smime.keystore:createSignedData

WmPublic. Creates signed S/MIME

data.

webMethods Integration Server Built-In Services Reference Version 9.6

696

Odd Header
SMIME Folder

Element

Package and Description

pub.smime.keystore:processEncryptedData

WmPublic. Decrypts an encrypted S/

MIME message.

pub.smime:createCertsOnlyData
WmPublic. Generates a PKCS #7 certs-only S/MIME entity from an array of certicates.
This service can be used to develop mechanisms for transmiing certicates and
certicate chains to other parties.
Input Parameters
certicates

byte[ ][ ] The certicates that are to be encapsulated within the

S/MIME entity. Each byte[ ] represents a single certicate.

Output Parameters
SMimeEnvStream

java.io.InputStream S/MIME entity.

Usage Notes
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.

pub.smime:createEncryptedData
WmPublic. Encrypts a MIME message.
Input Parameters
envStream

java.io.InputStream MIME message that you want to encrypt (for

example, the output produced by pub.mime:getEnvelopeStream).

recipientCerts

byte[ ][ ] The X.509 certicates of the recipients for whom this

message will be encrypted. Each element in the list represents
a certicate for a single recipient in the form of a byte[ ].
Note: When you have multiple recipients, createEncryptedData
creates a single message that is encrypted for all recipients. It
does not create a separate message for each recipient.

webMethods Integration Server Built-In Services Reference Version 9.6

697

Even Header
SMIME Folder

encryptionAlg

String Optional. Code specifying the encryption algorithm to

use. Must be TripleDES (default), DES, or RC2.

keyLength

String Optional. Length of the encryption key for RC2

encryption. Must be 40, 64, or 128 (default).
This parameter is ignored if encryptionAlg is not RC2.

Output Parameters
SMimeEnvStream

java.io.InputStream The encrypted MIME message.

Usage Notes
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.smime:createSignedData
pub.smime:processEncryptedData
pub.mime:getEnvelopeStream
Examples
See the following in the WmSamples package in the certied samples area
of the Knowledge Center on Empower Product Support website at hps://
empower.softwareag.com:
sample.smime:build_EncryptedSMime

pub.smime:createSignedAndEncryptedData
WmPublic. Deprecated - Replaced by pub.smime.keystore:createSignedAndEncryptedData.
Digitally signs a MIME message and then encrypts it.
Important: You must use this service when you want to create a message that is
both signed and encrypted. You cannot produce this type of message using the
pub.smime:createSignedData and pub.smime:createEncryptedData services.
Input Parameters
envStream

java.io.InputStream The MIME message that you want to

sign and encrypt (for example, the output produced by
pub.mime:getEnvelopeStream).

webMethods Integration Server Built-In Services Reference Version 9.6

698

Odd Header
SMIME Folder

privKey

byte[ ] Private key of the party signing the message.

certicates

byte[ ] [ ] Optional. The certicate chain of the party signing

the message, where each byte[ ] represents a single certicate
in the chain. Certicates must appear in hierarchical order,
starting with the signer's certicate in element 0. The following
list shows how the elements of a complete chain would appear
for a certicate that was issued through two intermediate CAs:
Element

Contents

Signer's certicate.

Intermediary CA Certicate.

Intermediary CA Certicate.

Root CA Certicate.

Note: Although this parameter is optional, it should only be

omied if the party receiving the message is able to process this
signature without an accompanying certicate chain.
signerCert

byte[ ] Digital certicate of the party signing the message.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is to be generated. Set to:
true to generate an explicit (detached) signature. This is the

default.

false to generate an implicit signature.

recipientCerts

byte[ ][ ] X.509 certicates of the recipients for whom this

message will be encrypted. Each element in the list contains
the certicate for a single recipient in the form of a byte array.

encryptionAlg

String Optional. Code specifying the encryption algorithm to

use. Must be TripleDES (default), DES, or RC2.

keyLength

String Optional. Length of the encryption key for RC2

encryption. Must be 40, 64, or 128 (default).
This parameter is ignored if encryptionAlg is not RC2.

webMethods Integration Server Built-In Services Reference Version 9.6

699

Even Header
SMIME Folder

Output Parameters
SMimeEnvStream

java.io.InputStream Signed and encrypted MIME message.

Usage Notes
This service is superseded by pub.smime.keystore:createSignedAndEncryptedData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide.
See Also
pub.smime:createEncryptedData
pub.smime:processEncryptedData
pub.smime:createSignedData
pub.smime:processSignedData
pub.smime.keystore:createSignedData
pub.mime:getEnvelopeStream
Examples
See the following in the WmSamples package in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.smime:build_SignedAndEncryptedSMime

pub.smime:createSignedData
WmPublic. Deprecated - Replaced by pub.smime.keystore:createSignedData. Digitally signs a
MIME message.
Input Parameters
envStream

java.io.InputStream MIME message that you want to sign (for

example, the output produced by pub.mime:getEnvelopeStream).

privKey

byte[] Private key of the party signing the message.

certicates

byte[ ][ ] Optional. Certicate chain of the party that signed

the message, where each byte[ ] represents a single certicate
in the chain. Certicates must appear in hierarchical order,
starting with the signer's certicate in element 0. The following

webMethods Integration Server Built-In Services Reference Version 9.6

700

Odd Header
SMIME Folder

shows how the elements of a complete chain would appear for

a certicate that was issued through two intermediate CAs:
Element

Contents

Signer's certicate.

Intermediary CA Certicate.

Intermediary CA Certicate.

Root CA Certicate.

Although this parameter is optional, it should only be omied

if the party receiving the message is able to process this
signature without an accompanying certicate chain.
signerCert

byte[ ] Digital certicate of the party signing the message.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is generated. Set to:
true to generate an explicit (detached) signature. This is the

default.

false to generate an implicit signature.

Output Parameters
SMimeEnvStream

java.io.InputStream The signed MIME message.

Usage Notes
This service is superseded by pub.smime.keystore:createSignedData.
For general information about MIME messages and using the MIME services, see the
MIME-S/MIME Developers Guide .
See Also
pub.smime:createEncryptedData
pub.mime:getEnvelopeStream

webMethods Integration Server Built-In Services Reference Version 9.6

701

Even Header
SMIME Folder

pub.smime:processCertsOnlyData
WmPublic. Extracts the certicates from a PKCS #7 certs-only S/MIME entity.
Input Parameters
SMimeEnvStream

java.io.InputStream The certs-only S/MIME entity.

Output Parameters
certicates

byte[ ][ ] The extracted certicates. Each element in the list

contains one of the extracted certicates represented as a
byte[ ].

pub.smime:processEncryptedData
WmPublic. Deprecated - Replaced by pub.smime.keystore:processEncryptedData.
Decrypts an encrypted S/MIME message.
Input Parameters
SMimeEnvStream

java.io.InputStream The encrypted S/MIME entity (for example,

the output produced by pub.smime:createEncryptedData).

recipientCert

byte[ ] Digital certicate of the party receiving the message.

privKey

byte[ ] Private key of the party receiving the message (that is,
the party whose public key was used to encrypt the message).

Output Parameters
mimeData

Document MIME object containing the decrypted MIME

message.

contentDigest

String Message digest of the encrypted content, base64encoded. (Some sites return this digest to the sender to
acknowledge their receipt of the message.)

webMethods Integration Server Built-In Services Reference Version 9.6

702

Odd Header
SMIME Folder

encrypted

String Conditional. Flag indicating whether the decrypted

MIME entity is encrypted. A value of:
true indicates that the MIME entity is encrypted.
false indicates that the MIME entity is not encrypted.

signed

String Conditional. Flag indicating whether the decrypted

MIME entity is signed. A value of:
true indicates that the MIME entity is signed.
false indicates that the MIME entity is not signed.

certsOnly

String Conditional. Flag indicating whether the decrypted

MIME entity is a certs-only entity. A value of:
true indicates that the MIME entity is a certs-only entity.
false indicates that the MIME entity is not a certs-only

entity.
stream

java.io.InputStream Conditional. The decrypted MIME entity.

Usage Notes
This service is superseded by pub.smime.keystore:processEncryptedData.
If the decrypted message is signed or encrypted, mimeData will be empty, and
the decrypted message will reside in stream . You can check the state of the signed
and encrypted output variables to determine whether the decrypted message
requires additional processing, and pass stream to the pub.smime:processSignedData or
pub.smime:processEncryptedData service as necessary.
Important: You can examine the contents of mimeData during testing and debugging.
However, because the internal structure of mimeData is subject to change without
notice, do not explicitly set or map data to/from these elements in your service. To
manipulate or access the contents of mimeData , use only the MIME services that
Integration Server provides.
See Also
pub.smime:processSignedData
pub.smime:createEncryptedData

pub.smime:processSignedData
WmPublic. Veries the signature from a signed S/MIME entity and extracts the message
from it.

webMethods Integration Server Built-In Services Reference Version 9.6

703

Even Header
SMIME Folder

Input Parameters
SMimeEnvStream

java.io.InputStream Signed MIME entity (for example, the output

produced by pub.smime:createSignedData).

signerCertChain

byte[ ][ ] Optional. Certicate chain of the party that signed

the message, where each byte[ ] represents a single certicate
in the chain. Certicates must appear in hierarchical order,
starting with the signer's certicate in element 0. The following
shows how the elements of a complete chain would appear for
a certicate that was issued through two intermediate CAs:
Element

Contents

Signer's certicate.

Intermediary CA Certicate.

Intermediary CA Certicate.

Root CA Certicate.

Note: If the signer included the certicate chain with the digital
signature, you do not need to supply signerCertChain .
Output Parameters
mimeData

Document MIME object containing the extracted MIME entity.

contentDigest

String Message digest (base64-encoded) that was recalculated

by processSignedData.

signerCert

java.security.cert.X509Certificate Signer's X.509 certicate.

encrypted

String Conditional. Flag indicating whether the extracted

MIME entity is encrypted. A value of:
true indicates that the MIME entity is encrypted.
false indicates that the MIME entity is not encrypted.

signed

String Conditional. Flag indicating whether the extracted

MIME entity is signed. A value of:

webMethods Integration Server Built-In Services Reference Version 9.6

704

Odd Header
SMIME Folder

true indicates that the MIME entity is signed.

false indicates that the MIME entity is not signed.

certsOnly

String Conditional. Flag indicating whether the extracted

MIME entity is a certs-only entity. A value of:
true indicates that the MIME entity is a certs-only entity.
false indicates that the MIME entity is not a certs-only

entity.
stream

java.io.InputStream Conditional. Extracted MIME entity.

verify

String Flag indicating whether the signature was successfully

processed. Success indicates that the signature was
successfully veried with the supplied public key. A value of:
true indicates that signature processing was successful.
false indicates that signature processing failed. The

signature could not be veried because an errorCode 1, 2, 3, or

4 occurred.
trusted

String Flag indicating whether the signer certicate is trusted

or not. A value of:
true indicates that the signer certicate is trusted.
false indicates that the signer certicate is not trusted.

errorCode

String Conditional. Number indicating the kind of error that

occurred while processing the signature. See errorMessage for
possible values.
If no error occurred, errorCode will not be returned.

errorMessage

String Conditional. Textual error message indicating what kind

of error occurred while processing the signature. Error codes
and messages are as follows:
errorCode

errorMessage

Invalid signer certificate file

information.

Certificate at index 'i' is not in

recognizable format.

webMethods Integration Server Built-In Services Reference Version 9.6

705

Even Header
SMIME Folder

Invalid certificate input at index 'i'.

Signature cannot be verified.

Expired certificate chain.

Error in certificate chain.

Untrusted certificate.

Usage Notes
If verify is false, the errorCode and errorMessage values will indicate the error that caused
the failure. Note that errorCode values 5 through 7 do not represent signature-validation
failures and, therefore, do not cause the verify ag to be set to false.
If the extracted entity is signed or encrypted, mimeData will be empty, and the extracted
entity will reside in stream . You can check the state of the signed and encrypted output
variables to determine whether the extracted entity requires additional processing, and
pass stream to the pub.smime:processEncryptedData service as necessary.
Important: You can examine the contents of mimeData during testing and debugging.
However, because the internal structure of mimeData is subject to change without
notice, do not explicitly set or map data to/from these elements in your service. To
manipulate or access the contents of mimeData , use only the MIME services that
Integration Server provides.
See Also
pub.smime:processEncryptedData
pub.smime:createSignedData
Examples
Important: See the following in the WmSamples packages in the certied samples
area of the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.smime:extract_SignedSMime
sample.smime:extract_SignedAndEncryptedSMime

pub.smime.keystore:createSignedAndEncryptedData
WmPublic. Digitally signs and encrypts a MIME message.

webMethods Integration Server Built-In Services Reference Version 9.6

706

Odd Header
SMIME Folder

Input Parameters
envStream

java.io.InputStream The MIME message that you want to

sign and encrypt (for example, the output produced by
pub.mime:getEnvelopeStream).

keyStoreAlias

String Alias of the keystore containing the signing key.

keyAlias

String Alias of the private key to be used for signing.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is to be generated. Set to:
True to generate an explicit (detached) signature. This is the

default.

False to generate an implicit signature.

recipientCerts

Object List A list of byte[ ] for the partner certicates for whom
this message will be encrypted.

encryptionAlg

String Optional. Code specifying the encryption algorithm to

use. Must be TripleDES (default), DES, or RC2.

keyLength

String Optional. Length of the encryption key for RC2

encryption. Must be 40, 64, or 128 (default).
This parameter is ignored if encryptionAlg is not RC2.

Output Parameters
SMimeEnvStream

java.io.InputStream Signed and encrypted data as a stream.

Usage Notes
This service supersedes pub.smime:createSignedAndEncryptedData
You must use this service when you want to create a message that is both signed and
encrypted.
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide

webMethods Integration Server Built-In Services Reference Version 9.6

707

Even Header
SMIME Folder

pub.smime.keystore:createSignedData
WmPublic. Creates signed S/MIME data.
Input Parameters
envStream

java.io.InputStream MIME message that you want to sign (for

example, the output produced by pub.mime:getEnvelopeStream).

keyStoreAlias

String Alias of the keystore.

keyAlias

String Alias of the private key of interest in the keystore.

explicit

String Optional. Flag indicating whether an implicit or explicit

signature is generated. Set to:
True to generate an explicit (detached) signature. This is the

default.

False to generate an implicit signature.

Output Parameters
SMimeEnvStream

java.io.InputStream The signed MIME stream.

Usage Notes
This service supersedes pub.smime:createSignedData.
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide.

pub.smime.keystore:processEncryptedData
WmPublic. Decrypts an encrypted S/MIME message.
Input Parameters
SMimeEnvStream

java.io.InputStream The encrypted S/MIME stream.

keyStoreAlias

String Alias of the keystore containing the decryption key.

webMethods Integration Server Built-In Services Reference Version 9.6

708

Odd Header
SMIME Folder

keyAlias

String Alias of the key used for decryption.

Output Parameters
mimeData

Document The decrypted MIME message.

contentDigest

String Message digest of the encrypted content, base64encoded. (Some sites return this digest to the sender to
acknowledge their receipt of the message.

encrypted

String Flag indicating whether the MIME entity passed in to

the service was encrypted. A value of:
True indicates that the MIME entity was encrypted.
False indicates that the MIME entity was not encrypted.

signed

String Flag indicating whether the MIME entity passed in to

the service was signed. A value of:
True indicates that the MIME entity is signed.
False indicates that the MIME entity is not signed.

certsOnly

String Flag indicating whether the MIME entity passed in to

the service contained only digital certicates. A value of:
True indicates that the MIME entity is a certs-only entity.
False indicates that the MIME entity is not a certs-only

entity.
stream

java.io.InputStream The decrypted MIME entity.

Usage Notes
This service supersedes pub.smime:processEncryptedData.
For information about using aliases for keystores, truststores, and private keys, see
webMethods Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

709

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

710

Odd Header
SOAP Folder

31 SOAP Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

712

711

Even Header
SOAP Folder

You use the elements in the soap folder to compose and send SOAP messages and to
receive and retrieve data from within them.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.soap.handler:addBodyBlock

WmPublic. Inserts a document into

a SOAP message as a new body
block.

pub.soap.handler:addFaultBlock

WmPublic. Inserts a document into

a SOAP message as a new fault
block.

pub.soap.handler:addHeaderBlock

WmPublic. Inserts a document into

a SOAP message as a new header
block.

pub.soap.handler:addHeaderElement

WmPublic. Deprecated - Replaced

by pub.soap.handler:addHeaderBlock.

pub.soap.handler:generateDocumentTypesFromWSDL

WmPublic. Generates IS document

types from a WSDL.

pub.soap.handler:getBodyBlock

WmPublic. Retrieves a body block

from a SOAP message.

pub.soap.handler:getBodyBlockQNames

WmPublic. Returns the QName

for each body block in a SOAP
message.

pub.soap.handler:getFaultBlock

WmPublic. Retrieves a fault block

from a SOAP message.

pub.soap.handler:getHeaderBlock

WmPublic. Retrieves a header

block from a SOAP message.

pub.soap.handler:getHeaderBlockQNames

WmPublic. Returns the QName

for each header block in a SOAP
message.

webMethods Integration Server Built-In Services Reference Version 9.6

712

Odd Header
SOAP Folder

Element

Package and Description

pub.soap.handler:getHeaderElement

WmPublic. Deprecated - Replaced

by pub.soap.handler:getHeaderBlock.

pub.soap.handler:getInitialSOAPRequest

WmPublic. Gets the initial SOAP

request message from a given
message context.

pub.soap.handler:getMessageAddressingProperties

WmPublic. Gets the value of the

specied message addressing
properties in a SOAP message.

pub.soap.handler:getProperty

WmPublic. Gets the value of a

specied property from a message
context.

pub.soap.handler:getServicePipeline

WmPublic. Gets the service

pipeline from a given message
context.

pub.soap.handler:getSOAPMessage

WmPublic. Gets the message

addressing properties of the SOAP
message in the provided message
context.

pub.soap.handler:getWebServiceInvocationProperties

WmPublic. Fetches the web service

invocation properties.

pub.soap.handler:handlerSpec

WmPublic. Specication to use as

the signature for a service that acts
as a header handler.

pub.soap.handler:hasFaultMessage

WmPublic. Determines whether the

SOAP message in a given message
context contains a SOAP fault
message.

pub.soap.handler:listConsumer

WmPublic. Returns a list of the

consumer handlers currently
registered on Integration Server.

webMethods Integration Server Built-In Services Reference Version 9.6

713

Even Header
SOAP Folder

Element

Package and Description

pub.soap.handler:listProvider

WmPublic. Returns a list of the

provider handlers currently
registered on Integration Server.

pub.soap.handler:registerConsumer

WmPublic. Deprecated
- Replaced by
pub.soap.handler:registerWmConsumer.

pub.soap.handler:registerProvider

WmPublic. Deprecated - Replaced

by pub.soap.handler:registerWmProvider.

pub.soap.handler:registerWmConsumer

WmPublic. Registers a handler for

use with consumer.

pub.soap.handler:registerWmProvider

WmPublic. Registers a header

handler for use with provider.

pub.soap.handler:removeBodyBlock

WmPublic. Removes a body block

from a SOAP message, leaving
an empty SOAP body, <SOAPENV:Body></SOAP-ENV:Body>.

pub.soap.handler:removeHeaderBlock

WmPublic. Removes a header block

from a SOAP message.

pub.soap.handler:removeHeaderElement

WmPublic. Deprecated - Replaced

by pub.soap.handler:removeHeaderBlock.

pub.soap.handler:removeProperty

WmPublic. Removes a property

from a message context.

pub.soap.handler:setProperty

WmPublic. Sets the value of a

specic property in a message
context.

pub.soap.handler:setSOAPMessage

WmPublic. Sets the SOAP message

in a message context.

pub.soap.handler:unregisterConsumer

WmPublic. Unregisters a consumer

web service descriptor handler.

webMethods Integration Server Built-In Services Reference Version 9.6

714

Odd Header
SOAP Folder

Element

Package and Description

pub.soap.handler:unregisterProvider

WmPublic. Unregisters a provider

web service descriptor handler.

pub.soap.handler:updateFaultBlock

WmPublic. Updates the fault code

(code ) and the fault string (reasons )
in the existing fault block.

pub.soap.processor:list

WmPublic. Deprecated - Returns

a list of the SOAP processors that
are currently registered on the
Integration Server.

pub.soap.processor:processMessage

WmPublic. Deprecated - Executes

the Integration Server's default
SOAP processor.

pub.soap.processor:processRPCMessage

WmPublic. Deprecated - Executes

the Integration Server's SOAP RPC
processor.

pub.soap.processor:registerProcessor

WmPublic. Deprecated - Registers a

service as a SOAP processor on the
Integration Server.

pub.soap.processor:unregisterProcessor

WmPublic. Deprecated - Unregisters

a SOAP processor by removing it
from the registry.

pub.soap.schema:encoding

WmPublic. Schema that denes the

data types SOAP supports.

pub.soap.schema:encoding_1_2

WmPublic. Schema that denes the

data types SOAP 1.2 supports.

pub.soap.schema:envelope

WmPublic. Schema that denes the

structure of a SOAP message.

pub.soap.schema:envelope_1_2

WmPublic. Schema that denes the

structure of a SOAP 1.2 message.

pub.soap.utils:addBodyEntry

WmPublic. Inserts an entry into the

body element of a SOAP message.

webMethods Integration Server Built-In Services Reference Version 9.6

715

Even Header
SOAP Folder

Element

Package and Description

pub.soap.utils:addHeaderEntry

WmPublic. Inserts an entry into the

header element of a SOAP message.

pub.soap.utils:addTrailer

WmPublic. Inserts a trailer in a

SOAP message.

pub.soap.utils:callbackServiceSpec

WmPublic. Denes the input

signature for an outbound callback
service.

pub.soap.utils:convertToVersionSpecificSOAPFault

WmPublic. Converts the generic

SOAP fault structure to the SOAP
version-specic fault structure that
is used by web service descriptors
created in versions of Integration
Server prior to 8.2.

pub.soap.utils:createSoapData

WmPublic. Creates a SOAP object

consisting of SOAP envelope, body,
and header entries.

pub.soap.utils:createXOPObject

WmPublic. Generates a
com.wm.util.XOPObject instance
from a base64Binary string, a byte
array, or an input stream.

pub.soap.utils:exitUnableToUnderstand

WmPublic. Terminates processing

and returns a mustUnderstand
fault to the client.

pub.soap.utils:getActor

WmPublic. Retrieves the value of

the actor aribute (for SOAP 1.1)
or the role aribute (for SOAP 1.2)
from a given header entry.

pub.soap.utils:getBody

WmPublic. Retrieves the body from

a SOAP message as a single node
object.

pub.soap.utils:getBodyEntries

WmPublic. Retrieves the body

entries from a SOAP message as an
array of node objects.

webMethods Integration Server Built-In Services Reference Version 9.6

716

Odd Header
SOAP Folder

Element

Package and Description

pub.soap.utils:getDocument

WmPublic. Retrieves an entire

SOAP message as a node object.

pub.soap.utils:getEncoding

WmPublic. Retrieves the encoding

from a SOAP message as a single
string.

pub.soap.utils:getHeader

WmPublic. Retrieves the header

from a SOAP message as a single
node object.

pub.soap.utils:getHeaderEntries

WmPublic. Retrieves the header

entries from a SOAP message as an
array of node objects.

pub.soap.utils:getMustUnderstand

WmPublic. Returns the

mustUnderstand status for a given
header entry.

pub.soap.utils:getQName

WmPublic. Returns the qualied

name for a given node.

pub.soap.utils:getTrailers

WmPublic. Retrieves the trailers

from a SOAP message.

pub.soap.utils:getXOPObjectContent

WmPublic. Retrieves the contents

of a com.wm.util.XOPObject
instance as a base64Binary string, a
byte array, or an InputStream.

pub.soap.utils:QName

WmPublic. Document type that

denes the structure of a qualied
name.

pub.soap.utils:removeBodyEntry

WmPublic. Deletes a body entry

from a SOAP message.

pub.soap.utils:removeHeaderEntry

WmPublic. Deletes a header entry

from a SOAP message.

pub.soap.utils:removeTrailer

WmPublic. Deletes a trailer from a

SOAP message.

webMethods Integration Server Built-In Services Reference Version 9.6

717

Even Header
SOAP Folder

Element

Package and Description

pub.soap.utils:requestResponseSpec

WmPublic. Denes the input/

output signature for a custom
processor and a target service for
the default processor.

pub.soap.utils:resetWSDEffectivePolicy

WmPublic. Returns the eective

policy for a handler in a web
service descriptor to the policy
set in the Policy name property in
Software AG Designer.

pub.soap.utils.setWSDEffectivePolicy

WmPublic. Sets the eective policy

for a handler in a web service
descriptor.

pub.soap.utils:soapDataToBytes

WmPublic. Converts a SOAP object

to a Byte Array.

pub.soap.utils:soapDataToString

WmPublic. Converts a SOAP object

to a String.

pub.soap.utils:soapFault

WmPublic. Document type that

denes the generic SOAP fault
structure used by web service
descriptors created in Integration
Server 8.2 and later.

pub.soap.utils:streamToSoapData

WmPublic. Converts an
InputStream containing a SOAP
message to a SOAP object.

pub.soap.utils:stringToSoapData

WmPublic. Converts a String

containing a SOAP message to a
SOAP object.

pub.soap.utils:validateSoapData

WmPublic. Veries that a SOAP

object represents a valid SOAP
message.

pub.soap.wsa:action

WmPublic. Document type

that denes the contents of the
wsa:Action WS-Addressing
header.

webMethods Integration Server Built-In Services Reference Version 9.6

718

Odd Header
SOAP Folder

Element

Package and Description

pub.soap.wsa:faultTo

WmPublic. Document type

that denes the contents of the
wsa:FaultTo WS-Addressing
header.

pub.soap.wsa:from

WmPublic. Document type that

contains the details of the source of
the message.

pub.soap.wsa:messageID

WmPublic. Document type

that denes the contents of the
wsa:MessageID WS-Addressing
header.

pub.soap.wsa:problemAction

WmPublic. Document type that

captures additional information
about faults.

pub.soap.wsa:problemHeaderQName

WmPublic. Document type that

captures additional information
about faults.

pub.soap.wsa:problemIRI

WmPublic. Document type that

captures the IRI that caused the
problem.

pub.soap.wsa:relatesTo

WmPublic. Document type

that denes the contents of the
wsa:RelatesTo WS-Addressing
header.

pub.soap.wsa:replyTo

WmPublic. Document type

that denes the contents of the
wsa:ReplyTo WS-Addressing
header.

pub.soap.wsa:retryAfter

WmPublic. Document type that

species the minimum duration
in milliseconds that Integration
Server waits before retransmiing a
message.

webMethods Integration Server Built-In Services Reference Version 9.6

719

Even Header
SOAP Folder

Element

Package and Description

pub.soap.wsa:to

WmPublic. Document type that

denes the contents of the wsa:To
WS-Addressing header.

pub.soap.wsa:schema_wsa

WmPublic. A schema containing

the elements from http://

www.w3.org/2005/08/addressing

namespace.
pub.soap.wsa.submission:action

WmPublic. Document type

that denes the contents of the
wsa:Action WS-Addressing
header.

pub.soap.wsa.submission:faultTo

WmPublic. Document type

that denes the contents of the
wsa:FaultTo WS-Addressing
header.

pub.soap.wsa.submission:from

WmPublic. Document type that

contains the details about the
source of the message.

pub.soap.wsa.submission:messageID

WmPublic. Document type

that denes the contents of the
wsa:MessageID WS-Addressing
header.

pub.soap.wsa.submission:relatesTo

WmPublic. Document type

that denes the contents of the
wsa:RelatesTo WS-Addressing
header.

pub.soap.wsa.submission:replyTo

WmPublic. Document type that

species the destination to which
the response message is to be sent.

pub.soap.wsa.submission:retryAfter

WmPublic. Document type that

species the minimum duration
in milliseconds that Integration
Server waits before retransmiing a
message.

webMethods Integration Server Built-In Services Reference Version 9.6

720

Odd Header
SOAP Folder

Element

Package and Description

pub.soap.wsa.submission:to

WmPublic. Document type that

denes the contents of the wsa:To
WS-Addressing header.

pub.soap.wsa.submission:schema_wsa_submission

WmPublic. A schema containing

the elements from http://
schemas.xmlsoap.org/
ws/2004/08/addressing

namespace.
pub.soap.wsrm:closeSequence

WmPublic. Closes a reliable

messaging sequence.

pub.soap.wsrm:createSequence

WmPublic. Sends a request to a

reliable messaging destination to
create a new reliable messaging
sequence.

pub.soap.wsrm:sendAcknowledgementRequest

WmPublic. Requests an
acknowledgment for a message
sequence.

pub.soap.wsrm:terminateSequence

WmPublic. Terminates a reliable

messaging sequence.

pub.soap.wsrm:waitUntilSequenceCompleted

WmPublic. Requests an
acknowledgment for a message
sequence.

pub.soap.handler:addBodyBlock
WmPublic. Inserts a document into a SOAP message as a new body block.
Input Parameters
messageContext

Object Message context containing the SOAP message to which to

add a body block.
A message context contains properties for the SOAP message and
provides access to the SOAP message. Integration Server creates
the message context and passes it to the handler. All handlers
invoked by a given instance of a SOAP request or SOAP response

webMethods Integration Server Built-In Services Reference Version 9.6

721

Even Header
SOAP Folder

use the same message context, which enables you to use the
message context to pass information among handlers.
documentType

String Optional. Fully qualied name of the IS document type

that species the structure of the document that you want to
add as a new body block; that is, that species the structure
of inputBodyBlock/bodyDocument . If specied, inputBodyBlock/
bodyDocument must be an instance of this document type.
Specify a document type that Integration Server created
while creating the consumer or the WSDL rst provider
web service descriptor or one that was created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.
If you do not specify a document type, the service performs a
literal conversion of inputBodyBlock/bodyDocument into the SOAP
body; that is, the conversion will not consider style or use.

inputBodyBlock

Document Contents of the body block.

Key

Description

operationQName

Document Optional. Qualied name for the

web service wrapper that the addBodyBlock
service will use to wrap the XML payload that
it generates by converting bodyDocument into
XML.
The operationQName document references the
pub.soap.utils:QName document type.
Note: The operationQName is only relevant for
RPC/Encoded and RPC/Literal services; this
service ignores operationQName for Document/
Literal services.

bodyDocument

Key

Description

namespaceName

String Namespace name for

the web service operation.

localName

String Name of the web

service operation on which
the handler is being wrien.

Document SOAP body block that you want to

add to the SOAP message. Integration Server

webMethods Integration Server Built-In Services Reference Version 9.6

722

Odd Header
SOAP Folder

converts the document to an XML node and

inserts it as a body block.
wrapPayloadWith
OperationQName
FromContext

String Optional. Flag that indicates whether the service should

obtain the qualied name for the web service wrapper from the
message context or from operationQName . Set to:
true to have the service obtain the qualied name for the web

service wrapper from messageContext . If the operationQName

parameters are specied, the service ignores them.
false to have the service use the values you specify in the

operationQName parameters. This is the default.

Note: For RPC/Encoded and RPC/Literal services, be sure to

set wrapPayloadWithOperationQNameFromContext to true
if you do not specify operationQName . This service ignores
wrapPayloadWithOperationQNameFromContext for Document/
Literal services.
validate

String Optional. Flag that indicates whether you want the service
to validate inputBodyBlock/bodyDocument against the IS document
type specied in the documentType input parameter. If you do not
use documentType to specify an IS document type, the validation
will fail.
Set validate to:
true to validate inputBodyBlock/bodyDocument . If the validation

fails, an exception is thrown.

false to skip validating inputBodyBlock/bodyDocument . This is

the default.

Output Parameters
status

String Flag indicating the outcome of the service. A value of:

true indicates that adding the body block was successful.
false indicates that adding the body block failed.

Note: If the SOAP message already contains a body block, the

service sets status to false.
Usage Notes
If the SOAP message already contains a body block, rst use the
pub.soap.handler:removeBodyBlock service to remove the existing body block before using
this service to add a new one.

webMethods Integration Server Built-In Services Reference Version 9.6

723

Even Header
SOAP Folder

See Also
pub.soap.handler:getBodyBlock
pub.soap.handler:removeBodyBlock

pub.soap.handler:addFaultBlock
WmPublic. Inserts a document into a SOAP message as a new fault block.
Input Parameters
messageContext

Object Message context containing the SOAP message to which

to add a fault block.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration Server
creates the message context and passes it to the handler. All
handlers invoked by a given instance of a SOAP request or
SOAP response use the same message context, which enables
you to use the message context to pass information among
handlers.

documentType

String Optional. Fully qualied name of the IS document

type that species the structure of the document in soapFault/
detail . If specied, soapFault/detail must be an instance of this
document type.
Specify a document type that Integration Server created
while creating the consumer or the WSDL rst provider
web service descriptor or one that was created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.
If you do not specify a document type, the service performs a
literal conversion of soapFault/detail ; that is, the conversion will
not consider style or use.

soapFault

Document SOAP fault block that you want to add to the SOAP
message. Integration Server converts the document to an XML
node and inserts it as a fault block.
Key

Descriptions

code

Document Contains the fault code and possible

subcodes.

webMethods Integration Server Built-In Services Reference Version 9.6

724

Odd Header
SOAP Folder

Key

Descriptions

namespaceName

String Namespace name for the

SOAP fault code.

localName

String Code that identies the

fault.

subCodes

Document List Optional. One or

more subcodes that provide
further detail. For each
subcode, include a Document
in the subCodes Document
List; each Document should
contain:
namespaceName for the
subcode
localName that identies the
subcode

reasons

Document List Reasons for the SOAP fault. Each

Document in the Document List contains a
human readable explanation of the cause of the
fault.
Key

Descriptions

*body

String Text explaining the

cause of the fault.

@lang

String Optional. Language

for the human readable
description.

node

String Optional. URI to the SOAP node where the

fault occurred.

role

String Optional. Role in which the node was

operating at the point the fault occurred.

detail

Document Optional. Application-specic details

about the SOAP fault.

webMethods Integration Server Built-In Services Reference Version 9.6

725

Even Header
SOAP Folder

validate

String Optional. Flag that indicates whether you want the

service to validate soapFault/detail against the IS document
type specied in the documentType input parameter. If you
do not use documentType to specify an IS document, the
validation will fail.
Set validate to:
true to validate soapFault/detail . If the validation fails, an

exception is thrown.

false to skip validating soapFault/detail This is the default.

Output Parameters
status

String Flag indicating the outcome of the service. A value of:

true indicates that adding the fault block succeeded.
false indicates that adding the fault block failed.

Note: If the SOAP message already contains a fault block, the

service sets status to false.
See Also
pub.soap.handler:getFaultBlock

pub.soap.handler:addHeaderBlock
WmPublic. Inserts a document into a SOAP message as a new header block.
Input Parameters
messageContext

Object Message context containing the SOAP message to which

to add a header block.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

726

Odd Header
SOAP Folder

documentType

String Name of the IS document type that species the

structure and namespaces of the document to use as a new
header block.
Specify a document type that Integration Server created
while creating the consumer or the WSDL rst provider
web service descriptor or one that was created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.
The QName of the rst element in the IS document type is
used as the QName of the header block to add to the SOAP
message.
The inputHeaderBlock /headerDocument must be a instance of
this document type.

inputHeaderBlock

Document Contains information used to create the header block

to add to the SOAP message.
Key

Description

mustUnderstand

String Optional. Flag that indicates

whether a mustUnderstand aribute
is added to the new header block. The
mustUnderstand aribute species
whether recipients (the actor or role
at which the header is targeted) are
required to process a header entry.
Recipients that cannot process a
mandatory header entry must reject the
message and return a SOAP fault.
Set to:
true to indicate that the aribute

mustUnderstand="true" will be added

to the header block. This indicates
that processing the header entry is
required.
false to indicate that the

mustUnderstand aribute will not

be added to the header block. This
indicates that processing the header
entry is optional.
There is no default value.
If you do not set mustUnderstand ,
Integration Server omits the
mustUnderstand aribute from the

webMethods Integration Server Built-In Services Reference Version 9.6

727

Even Header
SOAP Folder

header entry, which is equivalent to

seing mustUnderstand to false.
Note: In SOAP 1.2, the values of the
mustUnderstand aribute changed from
0 and 1 to True and False; however,
Integration Server processes both sets
of values the same and performs any
necessary conversions.
role

String Optional. Target of the header

entry. The value of role determines the
value of the actor or role aribute for the
header entry. The actor or role aribute
species a URI for the recipient of a
header entry.
There is no default value. If you do not
set role , Integration Server omits the
actor aribute from the header entry,
which is equivalent to seing role to
Ultimate receiver.
For SOAP 1.1, set to:
Ultimate receiver to omit the

actor aribute from the header block.

This indicates that the recipient is
the ultimate destination of the SOAP
message.
Next to add an actor aribute with the

value "hp://schemas.xmlsoap.org/
soap/actor/next" to the header block.

None to add an actor aribute with the

value "hp://www.w3.org/2003/05/
soap-envelope/role/none" to the header
block.
User-specied value to specify the target
of the header block. Typically, this will
be a URI.
For SOAP 1.2, set to:
Ultimate receiver to omit the

role aribute from the header block.

This indicates that the recipient is
the ultimate destination of the SOAP
message.

webMethods Integration Server Built-In Services Reference Version 9.6

728

Odd Header
SOAP Folder

Next to add a role aribute with the

value "hp://schemas.xmlsoap.org/
soap-envelope/role/next" to the header
block.
None to add a role aribute with the

value "hp://www.w3.org/2003/05/
soap-envelope/role/none" to the header
block.
User-specied value to specify the target
of the header block. Typically, this will
be a URI.
headerDocument

validate

Document Document to add as a header

block. Integration Server converts the
document to an XML node and inserts it
as a header block.

String Optional. Flag that indicates whether you want the

service to validate the inputHeaderBlock/headerDocument
document against the IS document type specied in
the documentType input parameter. If you do not use
documentType to specify an IS document type, the validation
will fail.
Set validate to:
true to validate inputHeaderBlock/headerDocument . If the
validation fails, an exception is thrown.
false to skip validating inputHeaderBlock/headerDocument .

This is the default.

Output Parameters
None.
Usage Notes
This service replaces pub.soap.handler:addHeaderElement, which is deprecated.
See Also
pub.soap.handler:getHeaderBlock
pub.soap.handler:removeHeaderBlock

webMethods Integration Server Built-In Services Reference Version 9.6

729

Even Header
SOAP Folder

pub.soap.handler:addHeaderElement
WmPublic. Deprecated - Replaced by pub.soap.handler:addHeaderBlock.
Inserts a document into a SOAP message as a new header element (block).
Input Parameters
messageContext

Object Message context containing the SOAP message to which

to add a header element.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

QName

Document Optional. Qualied name (namespace name and

local name) of the header element to add.
The QName document references the pub.soap.utils:QName
document type.
Note: If you do not specify QName value, you must specify
documentType .

headerDocument

Document Document to add as a header element. Integration

Server converts the document to an XML node and inserts it as
a child element of the header element specied in QName .

documentType

String Optional. Name of the IS document type that species

the structure and namespaces of the document to use as a
new header element. Integration Server uses the universal
name assigned to the IS document type to determine the
qualied name to use for the new header element. If you
specify documentType , headerDocument must be a instance of
this document type.
Note: If you do not specify documentType , you must specify
QName .

mustUnderstand

String Optional. Sets the value of the mustUnderstand aribute

for the new header element (block). The mustUnderstand
aribute species whether recipients (the actor or role at

webMethods Integration Server Built-In Services Reference Version 9.6

730

Odd Header
SOAP Folder

which the header is targeted) are required to process a header

entry. Recipients that cannot process a mandatory header
entry must reject the message and return a SOAP fault.
Set to:
true to indicate that processing the header entry is optional.
false to indicate that processing the header entry is

mandatory.

There is no default value.

If you do not set mustUnderstand , Integration Server omits
the mustUnderstand aribute from the header entry, which is
equivalent to seing mustUnderstand to false.
Note: In SOAP 1.2, the values of the mustUnderstand aribute
changed from 0 and 1 to True and False; however, Integration
Server processes both sets of values the same and performs any
necessary conversions.
actor

String Optional. Target of the header entry. The value of actor

determines the value of the actor or role aribute for the
header entry. The actor or role aribute species a URI for the
recipient of a header entry.
If you do not specify a value for actor , the actor or role
aribute will be blank in the SOAP header. In SOAP 1.1, this
indicates that the recipient is the ultimate destination of the
SOAP message. In SOAP 1.2, this is equivalent to supplying
that aribute with the value "hp://www.w3.org/2003/05/
soap-envelope/role/ultimateReceiver".
Note: In SOAP 1.2, the actor aribute is named role; however,
Integration Server processes both names the same and performs
any necessary conversions.

Output Parameters
None.
Usage Notes
QName and documentType are mutually exclusive. Even though the parameters are
optional, you must specify one or the other. If you do not specify either, Integration
Server displays the following error:
[ISS.0088.9422] One of the mutually exclusive parameter QName or
documentType is missing or invalid.

If you specify values for QName and documentType , Integration Server uses the QName
value and ignores documentType .

webMethods Integration Server Built-In Services Reference Version 9.6

731

Even Header
SOAP Folder

For more information about the mustUnderstand and actor aributes in SOAP 1.1,
see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at hp://
www.w3.org/TR/SOAP/.
For more information about the mustUnderstand and role aributes in SOAP 1.2, see the
Simple Object Access Protocol (SOAP) 1.2 specication at hp://www.w3.org/TR/SOAP12/.
Example
Suppose that messageContext contains a SOAP message with an empty SOAP header and
you want to add a header element by passing the pub.soap:handler:addHeaderElement service
the following input parameters:
Input Parameter

Provided Value

QName

namespaceName

userHandlerNamespaceName

localName

userHandlerLocalName

headerDocument

An instance of documentTypes:myNewHeader, which contains

a single eld of type String named myString . The value of
myString is: Value of myString field.

documentType

Not provided.

mustUnderstand

true

actor

soapActor

Execution of the pub.soap.handler:addHeaderElement service results in this SOAP header for

SOAP 1.1:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<HDR:userHandlerLocalName
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:HDR="userHandlerNamespaceName"

webMethods Integration Server Built-In Services Reference Version 9.6

732

Odd Header
SOAP Folder

SOAP-ENV:actor="soapActor" SOAP-ENV:mustUnderstand="1">
<myString>Value of myString field.</myString>
</HDR:userHandlerLocalName>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Integration Server uses HDR as the namespace prex for the namespace name of the
header.
See Also
pub.soap.handler:getHeaderElement
pub.soap.handler:removeHeaderElement

pub.soap.handler:generateDocumentTypesFromWSDL
WmPublic. Generates IS document types from a WSDL.
Input Parameters
wsdlURL

String Optional. Network accessible URL to a WSDL document

or the path to and name of a WSDL on the same le system as
the Integration Server.
Note: All the XML Schema denitions and WSDL documents
imported by or included by the target WSDL document must be
network accessible or on the local le system as well.

wsdlString

String Optional. WSDL document as a string.

Note: All the XML Schema denitions and WSDL documents
imported by or included by the target WSDL document must be
network accessible or on the local le system as well.

targetPackageName

String Name of the package in which to place the generated IS

document types on Integration Server.

targetFolderName

String Name of the folder in which to place the generated IS

document types. Use the format folder.subfolder to specify the
folder name. The folder must be empty or must not yet exist.

generateheaderDocs

String Optional. Flag indicating whether the service should

generate the documents corresponding to headers in the SOAP
messages described in the WSDL document. Set to:
true to generate the documents. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

733

Even Header
SOAP Folder

false to skip generating the documents.

generateBodyDocs

String Optional. Flag indicating whether the service should

generate the documents corresponding to SOAP body in the
SOAP messages described in the WSDL document. Set to:
true to generate the documents.
false to skip generating the documents. This is the default.

generateFaultDocs

String Optional. Flag indicating whether the service should

generate the documents corresponding to SOAP faults in the
SOAP messages described in the WSDL document. Set to:
true to generate the documents.
false to skip generating the documents. This is the default.

generateXOPObject
ForBase64Binary

String Optional. Flag indicating whether the service should

generate elds of type com.wm.util.XOPObject corresponding
to the xsd:base64Binary elements. Set to:
true to generate elds of type com.wm.util.XOPObject.
false to skip generating elds of type

com.wm.util.XOPObject. This is the default.

content
ModelCompliance

String Optional. Flag that species how strictly the service

represents content models from the XML Schema denition in
the generated IS document types. Set to:
Strict to generate the IS document type only if Integration

Server can represent the content models dened in the XML

Schema denition correctly. Document type generation fails
if Integration Server cannot accurately represent the content
models in the source XML Schema denition.
Currently, Integration Server does not support repeating
model groups, nested model groups, or the any aribute.
If you select strict compliance, Integration Server does
not generate an IS document type from any XML schema
denition that contains those items.
Lax to generate an IS document type that correctly represents

the content models for the complex types dened in the

XML schema denition, when possible. If Integration
Server cannot correctly represent the content model in the
XML Schema denition in the resulting IS document type,
Integration Server generates the IS document type using a
compliance mode of None.

webMethods Integration Server Built-In Services Reference Version 9.6

734

Odd Header
SOAP Folder

When compliance is set to lax, Integration Server will

generate the IS document type even if the content models in
the XML schema denition cannot be represented correctly.
None to generate an IS document type that does not

necessarily represent or maintain the content models in the

source XML Schema denition.
When compliance is set to none, Integration Server generates
IS document types the same way they were generated in
Integration Server releases prior to version 8.2.
Output Parameters
warnings

Document List Conditional. Contains any warnings encountered

while generating IS document types from the provided WSDL.

Usage Notes
wsdlURL and wsdlString are mutually exclusive. Even though the parameters are
optional, you must specify one or the other. If you do not specify either, Integration
Server displays the following error:
ISS.0088.9422 Either parameter {0} or {1} must be provided.

If you specify values for wsdlURL and wsdlString , Integration Server uses wsdlString
and ignores wsdlURL .
If the WSDL provided in wsdlURL or wsdlString is invalid, the service ends in error.
If the package specied in targetPackageName does not exist, the service ends in error.
If the folder specied in targetFolderName does not exist, Integration Server creates it
when the service executes.
If the folder specied in targetFolderName exists but is not empty, the service ends in
error.
If you want execute this service for the same WSDL more than once, make sure to
specify a dierent targetFolderName or delete the contents of targetFolderName before reexecuting the service for the WSDL again.
If the service ends in error, it throws any errors or warnings as an exception and does
not create any IS document types. However, if the service encounters warnings, it places
the warnings in the warnings eld and generates any IS document types.

pub.soap.handler:getBodyBlock
WmPublic. Retrieves a body block from a SOAP message.

webMethods Integration Server Built-In Services Reference Version 9.6

735

Even Header
SOAP Folder

Input Parameters
Object Message context containing the SOAP message from
which to retrieve the body block.

messageContext

A message context contains properties for the SOAP message

and provides access to the SOAP message. Integration Server
creates the message context and passes it to the handler. All
handlers invoked by a given instance of a SOAP request or
SOAP response use the same message context, which enables
you to use the message context to pass information among
handlers.
String Optional. Fully qualied name of the IS document type
that species the structure of the SOAP body block to be
retrieved from the SOAP message.

documentType

Specify a document type that Integration Server created

while creating the consumer or the WSDL rst provider
web service descriptor or one that was created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.
If you do not specify a document type, the service performs a
literal conversion of body block; that is, the conversion will not
consider style or use.
String Optional. Flag that indicates whether you want
the service to validate the document returned in the
outputBodyBlock/bodyDocument parameter against the IS
document type specied in the documentType input parameter.
If you do not use documentType to specify an IS document
type, the validation will fail.

validate

Set validate to:

true to validate the body block. If the validation fails, an

exception is thrown.

false to skip validating the body block. This is the default.

Output Parameters
outputBodyBlock

Document Contents of the body block.

Key

Description

operationQName

Document Qualied name for the web service

wrapper that wraps the XML payload. The

webMethods Integration Server Built-In Services Reference Version 9.6

736

Odd Header
SOAP Folder

service only returns operationQName for RPC/

Encoded and RPC/Literal services.
The operationQName document references the
pub.soap.utils:QName document type.

bodyDocument

Key

Description

namespaceName

String Namespace name for the

web service operation.

localName

String Name of the web service

operation on which the
handler is being wrien.

Contents of the body block. If documentType was

specied, the service uses the IS document type
to determine the structure of bodyDocument .
Otherwise, the service performs a literal
conversion of body block; that is, the conversion
will not consider style or use.

See Also
pub.soap.handler:addBodyBlock
pub.soap.handler:removeBodyBlock

pub.soap.handler:getBodyBlockQNames
WmPublic. Returns the QName for each body block in a SOAP message.
Note: RPC/Encoded and RPC/Literal services can have only one body block. However,
Document/Literal services can have multiple body blocks.
Input Parameters
messageContext

Object Message context containing the SOAP message from

which to retrieve the body block QNames.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration Server
creates the message context and passes it to the handler. All
handlers invoked by a given instance of a SOAP request or
SOAP response use the same message context, which enables

webMethods Integration Server Built-In Services Reference Version 9.6

737

Even Header
SOAP Folder

you to use the message context to pass information among

handlers.
Output Parameters
bodyBlockQNames

Document List A list of documents containing the qualied

names (namespace name and local name) for each body block.
The bodyBlockQName document references the
pub.soap.utils:QName document type.

See Also
pub.soap.handler:removeBodyBlock

pub.soap.handler:getFaultBlock
WmPublic. Retrieves a fault block from a SOAP message.
Input Parameters
messageContext

Object Message context containing the SOAP message from

which to retrieve the fault block.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration Server
creates the message context and passes it to the handler. All
handlers invoked by a given instance of a SOAP request or
SOAP response use the same message context, which enables
you to use the message context to pass information among
handlers.

documentTypes

String List Optional. Fully qualied name of the possible IS

document types that could represent the structure of soapFault/
detail .
Specify document types that Integration Server created
while creating the consumer or the WSDL rst provider
web service descriptor or ones that were created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.
If you do not specify any document type, the service performs
a literal conversion of the document; that is, the conversion
will not consider style or use.

validate

String Optional. Flag that indicates whether you want

the service to validate soapFault/detail against one of the

webMethods Integration Server Built-In Services Reference Version 9.6

738

Odd Header
SOAP Folder

IS document types specied in the documentTypes input

parameter.
Set validate to:
true to validate the contents of soapFault/detail .

To validate the service uses an IS document type from

documentTypes that matches the structure. If none of the IS
document types specied in documentTypes match, validation
fails. If you do not use documentTypes to specify IS document
types, the validation fails. If the validation fails, an exception
is thrown.
false to skip validating the contents of soapFault/detail . This

is the default.

Output Parameters
Document Contents of the fault block.
Key

Description

soapFault

Document The retrieved fault block.

Key

Description

code

Document Contains the fault code and possible subcodes.

Key

Descriptions

namespaceName

String Namespace name for the SOAP fault

code.

localName

String Code that identies the fault.

subCodes

Document List Subcodes that provide further

detail. Each Document in the subCodes
Document List contains:
namespaceName for the subcode
localName that identies the subcode

reasons

Document List Reasons for the SOAP fault. Each Document in

the Document List contains a human readable explanation of
the cause of the fault.

webMethods Integration Server Built-In Services Reference Version 9.6

739

Even Header
SOAP Folder

Key

Descriptions

*body

String Text explaining the cause of the fault.

@lang

String Optional. Language for the human

readable description.

node

String URI to the SOAP node where the fault occurred.

role

String Role in which the node was operating at the point the
fault occurred.

detail

Document Application-specic details about the SOAP fault.

See Also
pub.soap.handler:addFaultBlock

pub.soap.handler:getHeaderBlock
WmPublic. Retrieves a header block from a SOAP message.
Input Parameters
messageContext

Object Message context containing the SOAP message from

which to retrieve a header block.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

documentType

String Fully qualied name of the IS document type that

species the structure to apply to the content of the header
block.
Specify a document type that Integration Server created
while creating the consumer or the WSDL rst provider
web service descriptor or one that was created using the
pub.soap.handler:generateDocumentTypesFromWSDL service.

webMethods Integration Server Built-In Services Reference Version 9.6

740

Odd Header
SOAP Folder

Integration Server uses the QName of the rst eld of the

document type to determine which header block to retrieve
from the SOAP message.
validate

String Optional. Flag that indicates whether you want

the service to validate the document returned in the
outputHeaderBlock/headerDocument parameter against the IS
document type specied in the documentType input parameter.
Set validate to:
true to validate outputHeaderBlock/headerDocument . If the

validation fails, an exception is thrown.

false to skip validating outputHeaderBlock/headerDocument .

This is the default.

Output Parameters
outputHeaderBlock

Document List Content of the requested header block(s) as

IData. This service returns multiple header blocks if the
QName of the rst eld of the document type matches
multiple header blocks in the SOAP message.
Key

Description

mustUnderstand

String Flag indicating whether the

mustUnderstand aribute is present in
the retrieved header block. A value of:
true indicates that the header block

contained mustUnderstand="true".
false indicates that the

mustUnderstand aribute was

absent from the header block or
mustUnderstand="false".
role

String For a SOAP 1.1 message, species

the value of the actor aribute. For a
SOAP 1.2 message, species the value of
the role aribute.
The role parameter is not returned if the
actor aribute is absent from a SOAP 1.1
message or if the role aribute is absent
from a SOAP 1.2 message.

webMethods Integration Server Built-In Services Reference Version 9.6

741

Even Header
SOAP Folder

headerDocument

Document Contents of the header block.

The IS document type specied for
the documentType input parameter
determines structure of headerDocument

Usage Notes
This service replaces pub.soap.handler:getHeaderElement, which is deprecated.
If the very rst eld in the IS document type specied for documentType does not contain
a QName, the service returns an empty outputHeaderBlock and does not throw an error.
If the QName of the very rst eld in the IS document type specied for documentType
does not match a QName of a header block in the SOAP message, the service returns an
empty outputHeaderBlock and does not throw an error.
If the QName of the very rst eld in the IS document type specied for documentType
matches a QName of a header block in the SOAP message but the content of the
header block does not match the elds in the IS document type, then the retrieved
headerDocument fails validation with the error
[ISS.0088.9432] SOAP Header data does not conform to Header Record

See Also
pub.soap.handler:addHeaderBlock
pub.soap.handler:removeHeaderBlock

pub.soap.handler:getHeaderBlockQNames
WmPublic. Returns the QName for each header block in a SOAP message.
Input Parameters
messageContext

Object Message context containing the SOAP message from

which to retrieve the header block QNames.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

742

Odd Header
SOAP Folder

Output Parameters
headerBlockQNames

Document List A list of documents containing the qualied

names (namespace name and local name) in the header block.
The headerBlockQName document references the
pub.soap.utils:QName document type.

Usage Notes
You can use the pub.soap.handler:getHeaderBlockQNames to identify the header block
QNames in a SOAP message and then use pub.soap.handler:removeHeaderBlock to remove
specic header blocks.
See Also
pub.soap.handler:removeHeaderBlock

pub.soap.handler:getHeaderElement
WmPublic. Deprecated - Replaced by pub.soap.handler:getHeaderBlock.
Retrieves a header element from a SOAP message.
Input Parameters
messageContext

Object Message context containing the SOAP message from

which to retrieve a header element.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

QName

Document Optional. Qualied name (namespace name and

local name) of the header element to retrieve.
The QName document references the pub.soap.utils:QName
document type. If you do not specify QName , you must
specify documentType .

documentType

String Optional. Fully qualied name of the IS document

type that species the structure to impose on the resulting
document. Integration Server uses the explicit universal name

webMethods Integration Server Built-In Services Reference Version 9.6

743

Even Header
SOAP Folder

assigned to the document type to determine which header

element to retrieve from the SOAP message.
If you do not specify documentType , you must specify QName .
Output Parameters
outputHeaderDocumentDocument Header element from the SOAP message in the form
of a document (IData).
Usage Notes
QName and documentType are mutually exclusive. Even though the parameters are
optional, you must specify one or the other. If you do not specify either, Integration
Server displays the following error:
[ISS.0088.9422] One of the mutually exclusive parameter QName or
documentType is missing or invalid.

If you specify values for QName and documentType , Integration Server uses QName and
ignores documentType .
Example
Suppose that messageContext contains a SOAP message with the following header:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:user="userHandlerNamespaceName" xmlns:pfx="pfx1namespace"
xmlns:ns1="ns1namespace" xmlns:ns2="ns2namespace">
<SOAP-ENV:Header>
<user:userHandlerLocalName>
<pfx:myLocalName>
<ns1:myField>
<ns2:myFieldValue>someValue</ns2:myFieldValue>
</ns1:myField>
</pfx:myLocalName>
</user:userHandlerLocalName>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Additionally, suppose that pub.soap:handler:getHeaderElement uses the following input

values, where messageContext has already been obtained:
Input Parameter

Provided Value

QName

namespaceName

userHandlerNamespaceName

localName

userHandlerLocalName

webMethods Integration Server Built-In Services Reference Version 9.6

744

Odd Header
SOAP Folder

Input Parameter

Provided Value

documentType

documentTypes:myHeaderStructure
The structure of documentTypes:myHeaderStructure looks like this:

The prexes in documentTypes:myHeaderStructure refer to the

following namespaces.
Prefix

Namespace

myPrex

pfx1namespace

myNS1

ns1namespace

myNS2

ns2namespace

Execution of the pub.soap.handler:getHeaderElement service results in the following value for

outputHeaderDocument :

webMethods Integration Server Built-In Services Reference Version 9.6

745

Even Header
SOAP Folder

Integration Server uses the following conventions in outputHeaderDocument :

outputHeaderDocument always contains a document list named
HDRDOC1:localName . The document list contains the header retrieved by the
pub.soap.handler:getHeaderElement service.
Integration Server uses HDRDOC1 as the prex for the header element (block).
The value of HDRDOC1 is the namespace name portion of the QName. The
outputHeaderDocument/nsDecls document identies the namespace associated with
the namespace prex of the requested header element (block).
TheHDRDOC1:localName [0] document contains an nsDecls document that identies
the namespace prexes used within the retrieved header element. Integration Server
replaces the prexes used in the SOAP envelope with the prexes that the document
type species for the same namespaces.
Integration Server uses the same general structure when placing SOAP headers in
the pipeline for IS services acting as web services. For more information, see "Server
Conguration Parameters" in webMethods Integration Server Administrators Guide.
See Also
pub.soap.handler:addHeaderElement
pub.soap.handler:removeHeaderElement

pub.soap.handler:getInitialSOAPRequest
WmPublic. Gets the initial SOAP request message from a given message context.
Input Parameters
messageContext

Object Message context from which to retrieve the initial SOAP

request message.

webMethods Integration Server Built-In Services Reference Version 9.6

746

Odd Header
SOAP Folder

A message context contains properties for the SOAP message

and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.
Output Parameters
initialSOAPMessage

Object Object of type javax.xml.soap.SOAPMessage that

represents the initial SOAP request message.

Usage Notes
You can use the initial SOAP request message retrieved by this service in the outbound
callback service. For more information about outbound callback services, see
Web Services Developers Guide.
You can use the SOAP message retrieved by this service with any existing public service
that takes an object of type javax.xml.soap.SOAPMessage as input.
In case of consumer web service descriptors, the pub.soap.handler:getInitialSOAPRequest
service returns the initial outbound SOAP request that Integration Server builds just
before sending the SOAP request to the web service provider.

pub.soap.handler:getMessageAddressingProperties
WmPublic. Gets the message addressing properties of the SOAP message in the
provided message context.
Input Parameters
messageContext

Object Message context from which to retrieve the message

addressing property value.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

747

Even Header
SOAP Folder

Output Parameters
messageAddressing
Properties

Document Value of the specied message addressing property.

Key

Description

messageID

String Conditional. Unique identier of the

SOAP message.

relatesTo

Document List Conditional. Contains the relation

ship information to another SOAP message.
Key

Description

value

String Message ID of the related

message.

relationshipTypeString Conditional. The

relationship type.
action

String Conditional. WS-Addressing action

specied in the message addressing property of
the SOAP message.

to

Document Conditional. The endpoint reference

that species the address of the intended
receiver of the SOAP message. The to endpoint
reference includes:
aributes , which includes namespaceName,
localname, and their values.
address and its aributes and values.
referenceParameters
metadata and its aributes and elements
extensibleElements , which are any other
elements usually provided for future
extensions.

from

Document Conditional. The endpoint reference

that species the source of the SOAP message.
The from endpoint reference includes:

webMethods Integration Server Built-In Services Reference Version 9.6

748

Odd Header
SOAP Folder

aributes , which includes namespaceName,

localname, and their values.
address and its aributes and values.
referenceParameters
metadata and its aributes and elements.
extensibleElements , which are any other
elements usually provided for future
extensions.
replyTo

Document Conditional. The endpoint reference

that species the destination address of the
response (reply) message. The replyTo endpoint
reference includes:
aributes , which includes namespaceName,
localname, and their values.
address and its aributes and values.
referenceParameters
metadata and its aributes and elements.
extensibleElements , which are any other
elements usually provided for future
extensions.

faultTo

Document Conditional. The endpoint reference

that species the address to which the SOAP
fault messages are routed. The faultTo endpoint
reference includes:
aributes , which includes namespaceName,
localname, and their values.
address and its aributes and values.
referenceParameters
metadata and its aributes and elements.
extensibleElements , which are any other
elements usually provided for future
extensions.

pub.soap.handler:getProperty
WmPublic. Gets the value of a specied property from a message context.

webMethods Integration Server Built-In Services Reference Version 9.6

749

Even Header
SOAP Folder

Input Parameters
messageContext

Object Message context from which to retrieve a property

value.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to
pass information among handlers. For example, in a chain of
request header handlers, the rst request header handler could
set a message property that the second request header handler
retrieves.
String Name of the selected property whose value to retrieve.

key
Output Parameters
value

Object Value of the specied property.

Usage Notes
To access the contents of the service pipeline, use the
pub.soap.handler:getServicePipelineinstead of thepub.soap.handler:getProperty service.
See Also
pub.soap.handler:getServicePipeline
pub.soap.handler:removeProperty
pub.soap.handler:setProperty

pub.soap.handler:getServicePipeline
WmPublic. Gets the service pipeline from a given message context.
Input Parameters
messageContext

Object Message context from which to get the service pipeline.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance

webMethods Integration Server Built-In Services Reference Version 9.6

750

Odd Header
SOAP Folder

of a SOAP request or SOAP response use the same message

context, which enables you to use the message context to pass
information among handlers.
Output Parameters
servicePipeline

Document Document (IData) containing the service pipeline.

The contents of servicePipeline depend on whether the
pub.soap.handler:getServicePipeline service executes as part of
a consumer handler chain or a provider handler chain and
which type of handler service (request, response, or fault)
executes the service.
For this consumer
handler service...

servicePipeline contains...

Request handler
service

Contents of the web service connector

pipeline after any pipeline mapping or
manipulation occurs during execution
of the web service connector but just
before Integration Server sends the
SOAP request.

Response handler
service

The pipeline that becomes the web

service connector output pipeline. At
this point, the pipeline does not contain
data from SOAP response. Integration
Server adds the data form the SOAP
response after handler processing
completes.

Fault handler
service

The contents of the web service

connector output pipeline. At this point,
the pipeline does not contain data from
the SOAP fault. Integration Server adds
the data form the SOAP fault after
handler processing completes.

For this provider

handler service...

servicePipeline contains...

Request handler
service

The pipeline passed as input to the

endpoint service. At this point, the
pipeline does not yet contain data from
the SOAP request. Integration Server

webMethods Integration Server Built-In Services Reference Version 9.6

751

Even Header
SOAP Folder

places data from the SOAP request in

the pipeline after handler processing
completes
Response handler
service

The output pipeline of the endpoint

service that corresponds to the invoked
web service operation.
servicePipeline also contains data from
the SOAP request if the endpoint service
did not drop the data from the pipeline
during service execution.

Fault handler
service

The output pipeline of the endpoint

service that corresponds to the invoked
web service operation.
servicePipeline also contains data from
the SOAP request if the endpoint service
did not drop the data from the pipeline
during service execution.

Usage Notes
Use this service to give handler services access to the contents of the pipeline. The
handler service can then pass pipeline contents to another service. For example, during
execution of a handler service for a provider web service descriptor, you can use the
pub.soap.handler:getServicePipeline service to:
Pass pipeline data from the request handler service to the endpoint service.
Pass pipeline data from the endpoint service to the response handler service or fault
handler service.
During execution of a handler service for a consumer web service descriptor, you can
use the pub.soap.handler:getServicePipeline service to:
Pass pipeline data from the web service connector input to the request handler
service.
Pass pipeline data from the response handler service or fault handler service to the
web service connector output
Use the pub.soap.handler:getServicePipeline service to access the pipeline instead of using
thepub.soap.handler:getProperty service to access the servicePipeline property.

pub.soap.handler:getSOAPMessage
WmPublic. Gets the SOAP message from a given message context.

webMethods Integration Server Built-In Services Reference Version 9.6

752

Odd Header
SOAP Folder

Input Parameters
messageContext

Object Message context from which to get the SOAP message.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

Output Parameters
SOAPMessage

Object Object of type javax.xml.soap.SOAPMessage that

represents the SOAP message.

Usage Notes
You can use the SOAP message retrieved by this service with any existing public
service that takes an object of type javax.xml.soap.SOAPMessage as input. For
example, you can use the SOAP message as input for the pub.soap.utils:addBodyEntry or
pub.soap.utils:addHeaderEntry services.
See Also
pub.soap.handler:setSOAPMessage

pub.soap.handler:getWebServiceInvocationProperties
WmPublic. Fetches the web service invocation properties.
Input Parameters
messageContext

Object Optional. Message context containing the SOAP

message from which to retrieve the web service invocation
properties.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration Server
creates the message context and passes it to the handler. All
handlers invoked by a given instance of a SOAP request or
SOAP response use the same message context, which enables

webMethods Integration Server Built-In Services Reference Version 9.6

753

Even Header
SOAP Folder

you to use the message context to pass information among

handlers.
Output Parameters
soapAction

String SOAP action associated with the SOAP message request.

binderName

String Name of the WSBinder being invoked.

binding

String Binding against which the service was invoked.

portType

String Port type against which the service was invoked.

operationQName

Document Qualied name for the web service wrapper. The

service only returns operationQName for RPC/Encoded and
RPC/Literal services.

style

Key

Description

namespaceName

String Namespace name for the web

service operation.

localName

String Name of the web service

operation that was invoked.

String Style of the SOAP message. Possible values are:

document
rpc

use

String Use of the SOAP message. Possible values are:

literal
encoded

inbound

String Flag indicating whether the message is incoming or

outgoing. A value of:
true indicates that the SOAP message is incoming.
false indicates that the SOAP message is outgoing.

soapVersion

String SOAP version of the message. Possible values are:

SOAP11

webMethods Integration Server Built-In Services Reference Version 9.6

754

Odd Header
SOAP Folder

SOAP12

pub.soap.handler:handlerSpec
WmPublic. Specication to use as the signature for a service that acts as a header
handler.
Input Parameters
messageContext

Object Message context to be processed by the header handler.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

Output Parameters
statusCode

String Species the status of the handler service execution

which indicates the action Integration Server will take next.
The statusCode parameter must be an integer from 0-3.
The action Integration Server takes for a particular status
code depends on whether the service is registered as a
request handler, response handler, or fault handler. For more
information, see Web Services Developers Guide or Software AG
Designer Online Help.
If statusCode does not contain one of the specied values,
Integration Server assumes a value of 0.

faultMessage

String Conditional. Text to be used in the fault message.

Integration Server uses the faultMessage value for any handler
service that returns a status of 2 and when a response handler
service returns a status of 3. For more information, see
Web Services Developers Guide or Software AG Designer Online
Help.

Usage Notes
Services that act as header handlers do not need to use the pub.handler:handlerSpec
specication to dene the signature of the service. However, services that act as header

webMethods Integration Server Built-In Services Reference Version 9.6

755

Even Header
SOAP Folder

handlers must take the input parameters and produce the output parameters identied
in this specication.
This specication can be used as the signature for the any handler service (request,
response, or fault).
Integration Server altered handler chain processing in version 8.0 SP1. If
you want created in Integration Server version 7.x of 8.0 to use the handler
chain processing behavior available in Integration Server 7.x and 8.0, set the
wa.server.ws.71xHandlerChainBehavior server conguration parameter to true.
For more information about seing server conguration parameters, see webMethods
Integration Server Administrators Guide.
See Also
pub.soap.handler:registerWmConsumer
pub.soap.handler:registerWmProvider

pub.soap.handler:hasFaultMessage
WmPublic. Determines whether the SOAP message in a given message context contains
a SOAP fault message.
Input Parameters
messageContext

Object Message context from which to get the SOAP message.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

Output Parameters
hasFaultMessage

String Flag indicating whether the SOAP message contains a

SOAP fault. A value of:
True indicates the SOAP message contains a SOAP fault.
False indicates the SOAP message does not contain a SOAP

fault.

webMethods Integration Server Built-In Services Reference Version 9.6

756

Odd Header
SOAP Folder

pub.soap.handler:listConsumer
WmPublic. Returns a list of the consumer handlers currently registered on Integration
Server.
Input Parameters
None.
Output Parameters
Handlers

Document List A document list identifying the registered

consumer handlers on Integration Server. Information about
each consumer handler is contained in a separate document.
Key

Description

descriptiveName

String Descriptive name assigned to

the consumer handler when it was
registered.

className

String Class name of the handler.

policyType

String Conditional. Policy type of the

handler.
policyType does not apply to service
handlers.

handleRequestService

String Conditional. Fully qualied name

of the service used as the request header
handler. This parameter is returned
only if a request handler service was
registered with the consumer handler.

handleResponseService String Conditional. Fully qualied name

of the service used as the response
header handler. This parameter is
returned only if a response handler
service was registered with the
consumer handler.
handleFaultService

String Conditional. Fully qualied name

of the service used as the fault header
handler. This parameter is returned only

webMethods Integration Server Built-In Services Reference Version 9.6

757

Even Header
SOAP Folder

if a fault handler service was registered

with the consumer handler.
Headers

Document List List of QNames for

the headers (i.e., IS document types)
registered with the consumer handler.
Key

Description

namespace

String Namespace portion

of the header's qualied
name.

localName

String Local portion of the

header's qualied name.

pub.soap.handler:listProvider
WmPublic. Returns a list of the provider handlers currently registered on Integration
Server.
Input Parameters
None.
Output Parameters
Handlers

Document List A document list identifying the registered

consumer handlers on Integration Server. Information about
each consumer handler is contained in a separate document.
Key

Description

descriptiveName

String Descriptive name given to

the provider handler when it was
registered.

className

String Class name of the handler.

policyType

String Conditional. Policy type of the

handler.
policyType does not apply to service
handlers.

webMethods Integration Server Built-In Services Reference Version 9.6

758

Odd Header
SOAP Folder

handleRequestService

String Conditional. Fully qualied name

of the service used as the request header
handler. This parameter is returned
only if a request handler service was
registered with the provider handler.

handleResponseService String Conditional. Fully qualied name

of the service used as the response
header handler. This parameter is
returned only if a response handler
service was registered with the provider
handler.
handleFaultService

String Conditional. Fully qualied name

of the service used as the fault header
handler. This parameter is returned only
if a fault handler service was registered
with the provider handler.

Headers

Document List List of QNames for the

headers registered with the provider
handler.
Key

Description

namespace

String Namespace portion

of the header's qualied
name.

localName

String Local portion of the

header's qualied name.

pub.soap.handler:registerConsumer
WmPublic. Deprecated - Replaced by pub.soap.handler:registerWmConsumer.
Registers a handler based on JAX-RPC with a consumer Web service descriptor.
Input Parameters
descriptiveName

String Name that you want to assign to the SOAP consumer

handler.

webMethods Integration Server Built-In Services Reference Version 9.6

759

Even Header
SOAP Folder

handler

Object The instance of the handler object.

handlerInfo

Object Optional. The instance of the handlerInfo object.

Output Parameters
None.

pub.soap.handler:registerProvider
WmPublic. Deprecated - Replaced by pub.soap.handler:registerWmProvider.
Registers a handler based on JAX-RPC with a provider Web service descriptor.
Input Parameters
descriptiveName

String Name that you want to assign to the SOAP provider

handler.

handler

Object The instance of the handler object.

handlerInfo

Object Optional. The instance of the handlerInfo object.

Output Parameters
None.

pub.soap.handler:registerWmConsumer
WmPublic. Registers a handler for use with consumer.
Input Parameters
descriptiveName

String Name to assign to the consumer header handler. Each

consumer header handler must have a unique name.

QNameList

Document List Optional. Qualied names of the headers

on which the handler operates. In the document list, each
document references the pub.soap.utils:QName document type.

handleRequestService

String Optional. Fully qualied name of the service to use as

the request header handler.

webMethods Integration Server Built-In Services Reference Version 9.6

760

Odd Header
SOAP Folder

handleResponseService String Optional. Fully qualied name of the service to use as

the response header handler.
handleFaultService

String Optional. Fully qualied name of the service to use as

the fault header handler.

Output Parameters
None.
Usage Notes
This service replaces pub.soap.handler:registerConsumer, which is deprecated.
Before you register a consumer header handler, create the services that will act as the
request, response, and fault header handlers.
Integration Server stores information about registered header handlers in memory.
Integration Server does not persist registered header handler information across restarts.
Consequently, you must register header handlers each time Integration Server starts. To
accomplish this, create a service that registers a header handler and make that service a
start up service for the package that contains the services that act as header handlers.
You can use a consumer header handler with consumer (WSD) only.
Specify a value for QNameList if you want to associate with handler with one or more
QNames. Registering QNames with a handler provides the following benets:
Integration Server can perform mustUnderstand checking for the header with the
QName at run time. If a service receives a SOAP message in which a header requires
mustUnderstand processing by the recipient, Integration Server uses the header
QName to locate the handler that processes the header. Note that the handler must
be part of the handler chain for the WSD that contains the service.
When adding headers to a WSD, Designer populate the list of IS document types
that can be used as headers in the WSD with the IS document types whose QNames
were registered with the handlers already added to the WSD. If you add a IS
document type as a header to a WSD and the QName of that IS document type is not
associated with a handler, Designer add the header but display a warning stating
that there is not an associated handler.
When consuming WSDL to create a provider or consumer WSD, Integration Server
automatically adds a handler to the resulting WSD if the WSDL contains a QName
supported by the handler.
Use the pub.soap.handler:registerWmProvider service to register a header handler for use with
provider.
To unregister a consumer header handler, use the pub.soap.handler:unregisterConsumer
service.
If you specify a service that does not exist for handleRequest , handleResponse , or
handleFaultService , Integration Server throws this error:

webMethods Integration Server Built-In Services Reference Version 9.6

761

Even Header
SOAP Folder

[ISS.0088.9421] The service <serviceName> does not exist.

If a registered handler with the same descriptiveName already exists, Integration Server
throws this error.
[ISS.0088.9423] Service handler <handlerName> is already registered.

See Also
pub.soap.handler:registerWmProvider

pub.soap.handler:registerWmProvider
WmPublic. Registers a header handler for use with provider.
Input Parameters
descriptiveName

String Name to assign to the provider header handler. Each

provider header handler must have a unique name.

QNameList

Document List Optional. Qualied names of the headers

on which the handler operates. In the document list, each
document references the pub.soap.utils:QName document type.

handleRequestService

String Optional. Fully qualied name of the service to use as

the request header handler.

handleResponseService String Optional. Fully qualied name of the service to use as

the response header handler.
handleFaultService

String Optional. Fully qualied name of the service to use as

the fault header handler.

Output Parameters
None.
Usage Notes
This service replaces pub.soap.handler:registerProvider, which is deprecated.
Before you register a provider header handler, create the services that will act as the
request, response, and fault header handlers.
Integration Server stores information about registered header handlers in memory.
Integration Server does not persist registered header handler information across restarts.
Consequently, you need to register header handlers each time Integration Server starts.

webMethods Integration Server Built-In Services Reference Version 9.6

762

Odd Header
SOAP Folder

To accomplish this, create a service that registers a header handler and make that service
a start up service for the package that contains the services that act as header handlers.
You can use a provider header handler with provider only.
Specify a value for QNameList if you want to associate with handler with one or more
QNames. Registering QNames with a handler provides the following benets:
Integration Server can perform mustUnderstand checking for the header with the
QName at run time. If a service receives a SOAP message in which a header requires
mustUnderstand processing by the recipient, Integration Server uses the header
QName to locate the handler that processes the header. Note that the handler must
be part of the handler chain for the WSD that contains the service.
When adding headers to a WSD, Designer populate the list of IS document types
that can be used as headers in the WSD with the IS document types whose QNames
were registered with the handlers already added to the WSD. If you add a IS
document type as a header to a WSD and the QName of that IS document type is not
associated with a handler, Designer add the header but display a warning stating
that there is not an associated handler.
When consuming WSDL to create a provider or consumer WSD, Integration Server
automatically adds a handler to the resulting WSD if the WSDL contains a QName
supported by the handler.
Use the pub.soap.handler:registerProvider service to register a header handler for use with
consumer.
To unregister a provider header handler, use the pub.soap.handler:unregisterProvider service.
If you specify a service that does not exist for handleRequest , handleResponse , or
handleFaultService , Integration Server throws this error:
[ISS.0088.9421] The service <serviceName> does not exist.

If a registered handler with the same descriptiveName already exists, Integration Server
throws this error.
[ISS.0088.9423] Service handler <handlerName> is already registered.

See Also
pub.soap.handler:registerProvider

pub.soap.handler:removeBodyBlock
WmPublic. Removes a body block from a SOAP message, leaving an empty SOAP body,
<SOAP-ENV:Body></SOAP-ENV:Body>.
Input Parameters
messageContext

Object Message context that contains the SOAP message from

which to remove the body block.

webMethods Integration Server Built-In Services Reference Version 9.6

763

Even Header
SOAP Folder

A message context contains properties for the SOAP message

as well as providing access to the SOAP message. Integration
Server creates the message context and passes it to the handler.
All handlers invoked by a given instance of a SOAP request
or SOAP response use the same message context. This enables
you to use the message context to pass information between
handlers.
Output Parameters
None.
Usage Notes
If the service encounters any error when removing the body block, it throws an
exception.
If you execute the service against a SOAP message that already contains an empty SOAP
body, the service performs no action.
See Also
pub.soap.handler:addBodyBlock
pub.soap.handler:getBodyBlock

pub.soap.handler:removeHeaderBlock
WmPublic. Removes a header block from a SOAP message.
Input Parameters
messageContext

Object Message context that contains the SOAP message from

which to remove a header block.
A message context contains properties for the SOAP message
as well as providing access to the SOAP message. Integration
Server creates the message context and passes it to the header
handler. All handlers invoked by a given instance of a SOAP
request or SOAP response use the same message context. This
enables you to use the message context to pass information
between handlers.

QName

Object Optional. Qualied name of the header block to remove.

The QName document references the pub.soap.utils:QName
document type.
Note: Either QName or documentType must be supplied.

webMethods Integration Server Built-In Services Reference Version 9.6

764

Odd Header
SOAP Folder

documentType

String Optional. Fully qualied name of the IS document type

that corresponds to the structure of the header block that you
want to remove. Integration Server uses the QName of the rst
element in the IS document type to determine which header
block to remove.
Note: Either QName or documentType must be supplied.
String Optional. An integer representing the position of the
header block entry with the specied QName to remove. A
SOAP message can contain multiple header blocks with the
same QName. If you specify an index, Integration Server
removes that occurrence of the header block. Note that 0 (zero)
represents the rst header block with the specied QName.

index

If index is not provided, Integration Server removes all the

header blocks with a matching QName.
For example, if QName is myNSName:myLocalName and
index is 1, Integration Server removes the second occurrence of
the header block with the QName myNSName:myLocalName.
Output Parameters
status

String Indicates whether Integration Server removed the header block.

Key

Description

True

If index was specied, indicates that Integration Server

removed the header block with the specied QName at the
specied index.
If index was not specied, indicates that Integration Server
removed all the header blocks matching the specied
QName

False

If index was specied, indicates that Integration Server did

not remove the header block at the specied index.
For example, if QName is myNSName:myLocalName and
index is 1, and the SOAP message does not contain a second
header with the QName myNSName:myLocalName, the
status is false.
If index was not specied, indicates that Integration Server
did not remove at least one header block with the specied
QName.

webMethods Integration Server Built-In Services Reference Version 9.6

765

Even Header
SOAP Folder

Usage Notes
This service replaces pub.soap.handler:removeHeaderElement, which is deprecated.
Either QName or documentType must be supplied. If both are provided, Integration
Server uses QName and ignores documentType .

pub.soap.handler:removeHeaderElement
WmPublic. Deprecated - Replaced by pub.soap.handler:removeHeaderBlock.
Removes a header element (block) from a SOAP message.
Input Parameters
messageContext

Object Message context that contains the SOAP message from

which to remove a header element (block).
A message context contains properties for the SOAP message
as well as providing access to the SOAP message. Integration
Server creates the message context and passes it to the header
handler. All handlers invoked by a given instance of a SOAP
request or SOAP response use the same message context. This
enables you to use the message context to pass information
between handlers.

QName

Object Qualied name of the header element (block) to remove.

The QName document references the pub.soap.utils:QName
document type.

Output Parameters
status

String Indicates whether Integration Server successfully

removed the header element. A value of:
True indicates that Integration Server removed the header
element.
False indicates that Integration Server did not remove the
header element because the SOAP message did not contain a
header element that matched the provided QName .

See Also
pub.soap.handler:addHeaderElement
pub.soap.handler:getHeaderElement

webMethods Integration Server Built-In Services Reference Version 9.6

766

Odd Header
SOAP Folder

pub.soap.handler:removeProperty
WmPublic. Removes a property from a message context.
Input Parameters
messageContext

Object Message context from which to remove a property.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to
pass information among handlers. For example, in a chain of
request header handlers, the rst request header handler could
set a message property that the second request header handler
retrieves.

key

String Name of the property to remove.

Output Parameters
None.
Usage Notes
The SOAP message contains properties reserved for use by Integration Server.
Do not use pub.soap.handler:setProperty to set any of these properties or use
pub.soap.handler:removeProperty to remove any of these properties as it may result in
unpredictable behavior. The reserved properties are:
ContentType

@MESSAGE_USER_FROM_USER_NAME_TOKEN

originalContext

@MESSAGE_USER_FROM_X509_TOKEN

servicePipeline

@TRANSPORT_URL

style

@TRANSPORT_USER

use

webMethods Integration Server Built-In Services Reference Version 9.6

767

Even Header
SOAP Folder

See Also
pub.soap.handler:getProperty
pub.soap.handler:setProperty

pub.soap.handler:setProperty
WmPublic. Sets the value of a specic property in a message context.
Input Parameters
messageContext

Object Message context in which to set a property.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to
pass information among handlers. For example, in a chain of
request header handlers, the rst request header handler could
set a message property that the second request header handler
retrieves.

key

String Name of the property to set.

value

Object Value to assign to the specied property.

Output Parameters
None.
Usage Notes
The SOAP message contains properties reserved for use by Integration Server.
Do not use pub.soap.handler:setProperty to set any of these properties or use
pub.soap.handler:removeProperty to remove any of these properties as it may result in
unpredictable behavior. The reserved properties are:
ContentType

@MESSAGE_USER_FROM_USER_NAME_TOKEN

originalContext

@MESSAGE_USER_FROM_X509_TOKEN

servicePipeline

@TRANSPORT_URL

webMethods Integration Server Built-In Services Reference Version 9.6

768

Odd Header
SOAP Folder

style

@TRANSPORT_USER

use
See Also
pub.soap.handler:getProperty
pub.soap.handler:removeProperty

pub.soap.handler:setSOAPMessage
WmPublic. Sets the SOAP message in a message context.
Input Parameters
messageContext

Object Message context in which to set the SOAP message.

A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration
Server creates the message context and passes it to the
header handler. All handlers invoked by a given instance
of a SOAP request or SOAP response use the same message
context, which enables you to use the message context to pass
information among handlers.

SOAPMessage

Object of type javax.xml.soap.SOAPMessage to use to

overwrite the existing SOAP message in the message context.

Output Parameters
None.
Usage Notes
Use this service with caution, as it overwrites the entire SOAP message, including the
SOAP header, body, and fault.
See Also
pub.soap.handler:getSOAPMessage

pub.soap.handler:unregisterConsumer
WmPublic. Unregisters a consumer web service descriptor handler.

webMethods Integration Server Built-In Services Reference Version 9.6

769

Even Header
SOAP Folder

Input Parameters
descriptiveName

String Name of the consumer web service descriptor handler

that you want to unregister.

Output Parameters
None.

pub.soap.handler:unregisterProvider
WmPublic. Unregisters a provider web service descriptor handler.
Input Parameters
descriptiveName

String Name of the provider web service descriptor handler

that you want to unregister.

Output Parameters
None.

pub.soap.handler:updateFaultBlock
WmPublic. Updates the code, subcodes, reasons, node, and role in an existing fault
block.
Input Parameters
messageContext

Object Message context containing the SOAP message that

contains the fault block to be updated.
A message context contains properties for the SOAP message and
provides access to the SOAP message. Integration Server creates
the message context and passes it to the handler. All handlers
invoked by a given instance of a SOAP request or SOAP response
use the same message context, which enables you to use the
message context to pass information among handlers.
If the SOAP Message in messageContext does not contain a SOAP
fault, the service returns the status output parameter as false.

webMethods Integration Server Built-In Services Reference Version 9.6

770

Odd Header
SOAP Folder

soapFault

Document The IData instance to be used to update the values in

the fault block.
Key

Description

reasons

Document List Optional. Reasons for the SOAP fault.

Each Document in the Document List contains a
human readable explanation of the cause of the fault.

code

node

Key

Descriptions

*body

String Text explaining the cause of

the fault.

@lang

String Optional. Language for the

human readable description.

Document Optional. Contains the fault code and

possible subcodes.
Key

Description

namespaceName

String Namespace name for the

SOAP fault code.

localName

String Code that identies the fault.

subCodes

Document List Optional. Subcodes

that provide further detail.
Key

Description

namespaceName

String Namespace
name for the
subcode.

localName

String Code that

identies the
subcode.

String Optional. URI to the SOAP node where the

fault occurred.

webMethods Integration Server Built-In Services Reference Version 9.6

771

Even Header
SOAP Folder

role

String Optional. Role in which the node was

operating at the point the fault occurred.

Output Parameters
status

String Flag indicating whether the fault block was updated

successfully. A value of:
true indicates that the fault block was successfully updated.
false indicates that either a fault block is not present in the

messageContext parameter or that the fault block was not

successfully updated.
Usage Notes

You can use this service on a provider response handler or fault handler to update the
fault block so that the values for code, subcodes, reasons, node, and role that Integration
Server generates can be overridden by the custom values you specify.
If you are using this service to override the information in a fault block in a SOAP 1.1
message, keep the following points in mind:
If multiple reasons are specied, Integration Server uses only the rst reason
specied because SOAP 1.1 does not support multiple reasons.
If any subcodes or node values are specied, Integration Server ignores them
because subcodes and node elements are not available in the SOAP 1.1 fault
structure.
See Also
pub.soap.handler:addFaultBlock
pub.soap.handler:getFaultBlock

pub.soap.processor:list
WmPublic. Deprecated - Returns a list of the SOAP processors that are currently
registered on the Integration Server.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

772

Odd Header
SOAP Folder

Output Parameters
list

Document List List of processors currently registered on the server. Each

document in the list contains the following information:
Key

Description

directive

String Process directive that is assigned to the SOAP

processor.

svcName

String Fully qualied name of the service that

functions as the SOAP processor.

descriptiveName

String Descriptive comment that was given to the

SOAP processor when it was registered. This
element will be empty if the processor was not
registered with a descriptive comment.

validateSOAPMessage

String Flag indicating whether the SOAP message

handler validates the SOAP messages that this
processor sends and receives. A value of:
true indicates that messages are validated by

the SOAP message handler. Be aware that the

validation process checks only that the message
envelope is structured correctly. For example,
it checks the message has at least one body
element and there is at most one header element.
It does not validate any of the data carried by the
message.
This seing overrides the server's global

watt.server.SOAP.validateSOAPMessage

seing.

indicates that messages are not validated by the

SOAP message handler.
This seing overrides the server's global

watt.server.SOAP.validateSOAPMessage

seing.

If validateSOAPMessage is null, message validation

for the processor is determined by the server's
watt.server.SOAP.validateSOAPMessage seing.

webMethods Integration Server Built-In Services Reference Version 9.6

773

Even Header
SOAP Folder

Notes
This service is deprecated. There is not a replacement service.
See Also
pub.soap.processor:registerProcessor
pub.soap.processor:unregisterProcessor

pub.soap.processor:processMessage
WmPublic. Deprecated - Executes the Integration Server's default SOAP processor.
This service behaves exactly like the built-in default SOAP processor. However, this
service can be wrapped in a ow service, which enables you to create an accesscontrolled SOAP processor.
Input Parameters
soapRequestData

Object SOAP object containing the SOAP request submied to

the Integration Server by a client.

soapResponseData

Object Empty SOAP object that the service will use to compose
the SOAP response message.

Output Parameters
soapResponseData

Object SOAP object containing the SOAP response message

that is to be returned to the client.

Usage Notes
This service is deprecated. There is not a replacement service.
You invoke processMessage from a wrapper service that you create and register as a SOAP
processor on the Integration Server. To impose access control on the processor, you
assign an access control list (ACL) to the wrapper service.

pub.soap.processor:processRPCMessage
WmPublic. Deprecated - Executes the Integration Server's SOAP RPC processor.

webMethods Integration Server Built-In Services Reference Version 9.6

774

Odd Header
SOAP Folder

This service behaves exactly like the built-in SOAP RPC processor. However, this service
can be wrapped in a ow service, which enables you to create an access-controlled
SOAP processor.
Input Parameters
soapRequestData

Object SOAP object containing the SOAP request submied to

the Integration Server by a client.

soapResponseData

Object Empty SOAP object that the service will use to compose
the SOAP response message.

Output Parameters
soapResponseData

Object SOAP object containing the SOAP response message

that is to be returned to the client.

Usage Notes
This service is deprecated. There is not a replacement service.
You invoke processRPCMessage from a wrapper service that you create and register as a
SOAP processor on the Integration Server. To impose access control on the processor,
you assign an access control list (ACL) to the wrapper service.

pub.soap.processor:registerProcessor
WmPublic. Deprecated - Registers a service as a SOAP processor on the Integration
Server.
Input Parameters
directive

String Process directive that you want to assign to the SOAP

processor.
Note: Use only leers, digits, or the characters -_.!~*'( ) in the
name you specify in directive .

svcName

String Fully qualied name of the service that you are

registering as a SOAP processor.

descriptiveName

String Descriptive comment for this SOAP processor.

This comment is shown when you run the utility service

webMethods Integration Server Built-In Services Reference Version 9.6

775

Even Header
SOAP Folder

pub.soap.processor:list to get a list of the registered SOAP

processors.
validateSOAPMessage String Optional. Flag indicating whether the SOAP message
handler validates the SOAP messages that this processor sends
and receives. Set to:
true to validate messages sent and received by this SOAP

processor. Be aware that the validation process checks

only that the message envelope is structured correctly. For
example, it checks the message has at least one body element
and there is at most one header element. It does not validate
any of the data carried by the message.
This seing overrides the server's global

watt.server.SOAP.validateSOAPMessage seing.
false to bypass validation on messages sent and received by

this SOAP processor.

This seing overrides the server's global

watt.server.SOAP.validateSOAPMessage seing.

Or, leave validateSOAPMessage null to validate

messages according to the Integration Server's
watt.server.SOAP.validateSOAPMessage seing. This is
the default.
Output Parameters
None.
Usage Notes
This service is deprecated. There is not a replacement service.
See Also
pub.soap.processor:list
pub.soap.processor:unregisterProcessor

pub.soap.processor:unregisterProcessor
WmPublic. Deprecated - Unregisters a SOAP processor by removing it from the registry.
Input Parameters
directive

String Process directive that you want to remove from the

registry. Directive names are case sensitive.

webMethods Integration Server Built-In Services Reference Version 9.6

776

Odd Header
SOAP Folder

Tip: To obtain a list of the current SOAP processor directives

registered on the server, run the pub.soap.processor:list service.
Output Parameters
None.
Usage Notes
This service is deprecated. There is not a replacement service.
If the directive specied in directive is not registered on the Integration Server,
unregisterProcessor throws an exception.
See Also
pub.soap.processor:list
pub.soap.processor:registerProcessor

pub.soap.schema:encoding
WmPublic. Schema that denes the data types SOAP supports.

pub.soap.schema:encoding_1_2
WmPublic. Schema that denes the data types SOAP 1.2 supports.

pub.soap.schema:envelope
WmPublic. Schema that denes the structure of a SOAP message.

pub.soap.schema:envelope_1_2
WmPublic. Schema that denes the structure of a SOAP 1.2 message.

pub.soap.utils:addBodyEntry
WmPublic. Inserts an entry into the body element of a SOAP message.

webMethods Integration Server Built-In Services Reference Version 9.6

777

Even Header
SOAP Folder

Input Parameters
soapData

Object SOAP object to which you want the body entry added.

bodyEntry

com.wm.lang.xml.Node XML node containing the body entry that

you want to add to soapData .
Note: An XML node is a parsable representation of a node in an
XML document. You generate an XML node using services such
as pub.xml:xmlStringToXMLNode.
Important: This service adds a single body entry to a SOAP
object. If you need to add more than one entry, execute
pub.soap.utils:addBodyEntry once for each entry.
Important: In webMethods Integration Server versions 6.0.1 and
later, this service expects the node in bodyEntry to be namespace
qualied. If the node is not qualied, the service throws an
exception. If you created solutions based on the earlier behavior
of this service (which permied non-qualied entries), you
can disable namespace enforcement by seing the server's
watt.server.SOAP.EnforceMsgPartNS parameter to false.

Output Parameters
soapData

Object SOAP object to which the body entry was added.

Usage Notes
A SOAP object is an object that represents a SOAP message.
If you are composing a new SOAP message, you must rst create an empty SOAP object
(called soapData ) with the createSoapData service and then add your header entries to
with pub.soap.utils:addHeaderEntry.
If you are composing a SOAP response, you use pub.soap.utils:addBodyEntry to populate
the soapResponseData object that the SOAP message handler generates and puts in the
pipeline.
See Also
pub.soap.utils:createSoapData
pub.soap.utils:addBodyEntry
pub.soap.utils:addHeaderEntry
pub.soap.utils:addTrailer
pub.soap.utils:getBody

webMethods Integration Server Built-In Services Reference Version 9.6

778

Odd Header
SOAP Folder

Examples
See the following in the WmSamples packages in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.soap:buildMsg_sendHTTP
sample.soap:customProc_msgQuwue
sample.soap:targetSvc_defaultProc

pub.soap.utils:addHeaderEntry
WmPublic. Inserts an entry into the header element of a SOAP message.
Input Parameters
soapData

Object SOAP object to which you want the header entry added.

headerEntry

com.wm.lang.xml.Node XML node containing the entry that you

want to add to soapData .
Note: An XML node is a parsable representation of a node in an
XML document. You generate an XML node using services such
as pub.xml:xmlStringToXMLNode.
Important: This service adds a single header entry to a SOAP
object. If you need to add more than one entry, execute
addHeaderEntry once for each entry.
Important: In webMethods Integration Server versions 6.0.1
and later, this service expects the node in headerEntry to be
namespace qualied. If the node is not qualied, the service
throws an exception. If you created solutions based on the
earlier behavior of this service (which permied non-qualied
entries), you can disable namespace enforcement by seing the
server's watt.server.SOAP.EnforceMsgPartNS parameter to
false.

mustUnderstand

String Optional. Value to which you want the mustUnderstand

aribute set.
The mustUnderstand aribute species whether recipients are
required to process a header entry (that is, whether processing
of the entry is mandatory or optional). Recipients that cannot

webMethods Integration Server Built-In Services Reference Version 9.6

779

Even Header
SOAP Folder

process a mandatory header entry must reject the message and

return a SOAP fault.
A value of:
0 indicates that the header is optional.
1 indicates that the header is mandatory.
For additional information about the mustUnderstand
aribute, see the Simple Object Access Protocol (SOAP) 1.1 - W3C
Note 08 May 2000 at hp://www.w3.org/TR/SOAP/.
Note: If you do not set mustUnderstand , the mustUnderstand
aribute is omied from the header entry, which is equivalent to
seing mustUnderstand to 0.
actor

String Optional. Value to which you want the actor aribute

set.
The actor aribute species a URI that identies the recipient
to which a header entry is targeted. For additional information
about the mustUnderstand aribute, see the Simple Object
Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at hp://
www.w3.org/TR/SOAP/.

Output Parameters
soapData

Object SOAP object to which the header entry was added.

Usage Notes
A SOAP object is an object that represents a SOAP message.
If you are composing a new SOAP message, you must rst create an empty SOAP object
(called soapData ) with the createSoapData service and then add your header entries to
with pub.soap.utils:addHeaderEntry.
If you are composing a SOAP response, you use addHeaderEntry to populate the
soapResponseData object that the SOAP message handler generates and puts in the
pipeline.
See Also
pub.soap.utils:createSoapData
pub.soap.utils:addBodyEntry
pub.soap.utils:addTrailer
pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries

webMethods Integration Server Built-In Services Reference Version 9.6

780

Odd Header
SOAP Folder

Examples
See the following in the WmSamples packages in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.soap:buildMsg_sendHTTP
sample.soap:targetSvc_defaultProc

pub.soap.utils:addTrailer
WmPublic. Inserts a trailer in a SOAP message.
(A trailer is an arbitrary element that follows the Body element in the SOAP envelope.)
Important: It appears likely that trailers will not be permied in future versions of SOAP
(versions 1.2 and later). If you are designing a completely new solution, we recommend
that you avoid using trailers. However, if you exchange SOAP messages with older
systems that already make use of trailers, this service allows you to insert them into a
SOAP message.
Input Parameters
soapData

Object SOAP object to which you want the trailer added.

trailer

com.wm.lang.xml.Node XML node containing the trailer that you

want to add to soapData .
Note: An XML node is a parsable representation of a node in an
XML document. You generate an XML node using services such
as pub.xml:xmlStringToXMLNode.
Important: This service adds a single trailer to a SOAP object. If
you need to insert more than one trailer in the message, execute
addTrailer once for each trailer that needs to be added.
Note: The SOAP specication states that trailers must be
namespace qualied, so be sure that the node in trailer species
a namespace.

Output Parameters
soapData

Object SOAP object to which the trailer was added.

webMethods Integration Server Built-In Services Reference Version 9.6

781

Even Header
SOAP Folder

Usage Notes
A SOAP object is an object that represents a SOAP message.
If you are composing a new SOAP message, you must rst create an empty SOAP
object (called soapData ) with the createSoapData service and then add your header
entries to with pub.soap.utils:addHeaderEntry.
If you are composing a SOAP response, you use pub.soap.utils:addHeaderEntry to
populate the soapResponseData object that the SOAP message handler generates and
puts in the pipeline.
See Also
pub.soap.utils:createSoapData
pub.soap.utils:addHeaderEntry
pub.soap.utils:addBodyEntry
pub.soap.utils:getTrailers

pub.soap.utils:callbackServiceSpec
WmPublic. Denes the input signature for an outbound callback service.
Input Parameters
messageContext

Object Message context to be processed by the outbound callback

service.
A message context contains properties for the SOAP message
and provides access to the SOAP message. Integration Server
creates the message context and passes it to the outbound callback
service.

Output Parameters
None.

pub.soap.utils:convertToVersionSpecificSOAPFault
WmPublic. Converts the generic SOAP fault structure to the SOAP version-specic fault
structure that is used by web service descriptors created in versions of Integration Server
prior to 8.2.

webMethods Integration Server Built-In Services Reference Version 9.6

782

Odd Header
SOAP Folder

Input Parameters
soapProtocol

String Optional. SOAP protocol with which the SOAP fault to

convert works. Valid values are SOAP 1.1 Protocol or SOAP 1.2
Protocol. The default is SOAP 1.2 Protocol.

fault

Document The generic SOAP fault that is to be converted.

The fault document references the pub.soap.utils:soapFault document
type.

Output Parameters
SOAPFAULT

Document Document containing the converted SOAP fault.

Key

Description

soapProtocol

String Indicates the SOAP protocol to which the SOAP

object works. This is the same as the soapProtocol input
parameter. Valid values are SOAP 1.1 Protocol or SOAP
1.2 Protocol.

Fault_1_1

Document Conditional. Converted fault information.

Faut_1_1 and its child variables are populated only when
soapProtocol is SOAP 1.1 Protocol.
Key

Description

faultcode

String Conditional. A code that identies the

fault. This eld corresponds to the SOAP 1.1
faultcode element.
This eld is set based on the value of the
code/namespaceName eld of the fault input
parameter. When namespaceName contains:
http://schemas.xmlsoap.org/soap/envelope/,
which is the standard namespace name for
a SOAP 1.1 Envelope, faultcode is set to the
following:
SOAP-ENV:localName
Any other value, faultcode is set to the
following:

webMethods Integration Server Built-In Services Reference Version 9.6

783

Even Header
SOAP Folder

{namespaceName}localName
In the above, localName is the value of the
code/localName eld and namespaceName is
value of the code/namespaceName eld of the
fault input parameter
faultstring

String Conditional. A human readable

explanation of the fault. This eld
corresponds to the SOAP 1.1 faultstring
element.
The service maps the *body value from the
rst reasons document of the fault input
parameter.

faultactor

String Conditional. Information about the

cause of the fault. This eld corresponds to
the SOAP 1.1 faultactor element.
The service maps the value from the role
eld of the fault input parameter.

detail

Document Conditional. Application-specic

details about the SOAP fault. This eld
corresponds to the SOAP 1.1 detail
element.
The service maps the value from the detail
eld of the fault input parameter.

Fault_1_2

Document Conditional. Converted fault information.

Fault_1_2 and its child variables are populated only when
soapProtocol is SOAP 1.2 Protocol.
Key

Description

SOAPENV:Code

Document Conditional. Contains the fault

code.
SOAPENV:Value

String A code that identies the

fault. This corresponds to the
SOAP 1.2 Code element.
This eld is set based
on the value of the code/
namespaceName eld of the

webMethods Integration Server Built-In Services Reference Version 9.6

784

Odd Header
SOAP Folder

fault input parameter. When

namespaceName contains:
http://www.w3.org/2003/05/
soap-envelope, which is,
the standard namespace
name for a SOAP 1.2
Envelope, faultcode is set to
the following:
SOAP-ENV:localName
Any other value, faultcode is set
to the following:
{namespaceName}localName
In the above, localName is the
value of the code/localName
eld and namespaceName
is value of the code/
namespaceName eld of the
fault input parameter
SOAPENV:Reason

Document Conditional. Document containing

the reason for the SOAP fault. This
corresponds to the SOAP 1.2 Reason
element.
SOAPEnv:Text

Document Conditional.
Document containing the
human readable explanation
of the cause of the fault.
The service maps the rst
document of the reasons eld
of the fault input parameter.
@XML:lang

webMethods Integration Server Built-In Services Reference Version 9.6

StringConditional.Species
the language
for the human
readable
description. This
eld corresponds
to the xml:lang
aribute of
the Text child
element of the
SOAP1.2 Reason
element.

785

Even Header
SOAP Folder

*body

SOAPENV:Node

String
Conditional.
Text explaining
the cause of the
fault. This eld
corresponds to
the Text child
element of the
SOAP 1.2 Reason
element.

String Conditional. URI to the SOAP

node where the fault occurred. This eld
corresponds to the SOAP 1.2 Node element.
The service maps the value from the node
eld of the fault input parameter.

SOAPENV:Role

String Conditional. Role in which the

node was operating at the point the fault
occurred. This eld corresponds to the
SOAP 1.2 Role element.
The service maps the value from the role
eld of the fault input parameter.

SOAPENV:Detail

Document Conditional. Application- specic

details about the SOAP fault. This eld
corresponds to the SOAP 1.2 Detail
element.
The service maps the value from the detail
eld of the fault input parameter.

Usage Notes
The following are instances where Integration Server generates a generic SOAP fault
structure that you might want to convert to a SOAP version-specic fault structure:
The fault output parameter from a web service connector generated from a web
service descriptor created in Integration Server 8.2.
The soapFault output parameter from the pub.soap.handler:getFaultBlock service.
The following lists instances where the service might not be able to convert all data in
the generic SOAP fault structure to a corresponding eld in the output.
The data in the code/subcodes eld of the fault input parameter does not map to any
output parameter. As a result, the service does not convert the data for either the
SOAP 1.1 or SOAP 1.2 protocol.

webMethods Integration Server Built-In Services Reference Version 9.6

786

Odd Header
SOAP Folder

The service might not be able to map all the data in the reasons eld of the fault input
parameter to the corresponding output parameters. The reasons eld is a Document
List that can represent the reason in multiple languages. However, the output can
represent only a single value.
For the SOAP 1.1 protocol, the service maps the *body from the rst Document of
the fault/reasons input parameter to the Fault_1_1/faultstring output parameter.
For the SOAP 1.2 protocol, the service maps only the rst Document of the fault/
reasons to the output parameter Fault_1_2/SOAP-ENV:Reason/SOAP-Env:Text .
The data in the node eld of the fault input parameter does not map to any element
of the Fault_1_1 output parameter. As a result, the service does not convert the value
for the SOAP 1.1 protocol.
See Also
pub.soap.handler:getFaultBlock

pub.soap.utils:createSoapData
WmPublic. Creates a SOAP object consisting of SOAP envelope, body, and header
entries.
Input Parameters
encoding

String Optional. Species the encoding method. Default value

is UTF-8.

addEmptyHeader

String Optional. Species whether to create an empty header

entry along with the SOAP envelope and body entries in the
SOAP message. Set to:
True to create an empty header entry in the SOAP message.
False to create only the SOAP envelope and body entries.

This seing overrides the global

wa.server.SOAP.addEmptyHeader seing of Integration
Server.
Important: There is no default value. If you do not specify
a value for the addEmptyHeader parameter, the service
adds an empty header entry, which is equivalent to seing
addEmptyHeader to True.
soapProtocol

String Optional. Indicates the SOAP protocol that the SOAP

object works with. The default value is read from the
wa.server.SOAP.defaultProtocol property. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

787

Even Header
SOAP Folder

SOAP 1.1 protocol to indicate the SOAP object works with

SOAP 1.1.

SOAP 1.2 protocol to indicate the SOAP object works with

SOAP 1.2.
Output Parameters
soapData

Object SOAP object.

Usage Notes
The encoding parameter can support incoming SOAP messages in any encoding.
Outgoing messages, however, are always encoded in UTF-8.
See Also
pub.soap.utils:addHeaderEntry
pub.soap.utils:addBodyEntry
pub.soap.utils:addTrailer
Examples
See the following in the WmSamples package in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.soap:buildMsg_sendHTTP

pub.soap.utils:createXOPObject
WmPublic. Generates a com.wm.util.XOPObject instance from a base64Binary string, a
byte array, or an input stream.
Input Parameters
contentType

String Optional. MIME type of the input data.

data

Document Data from which you want to generate a

com.wm.util.XOPObject instance.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

788

Odd Header
SOAP Folder

base64String

String Optional. The base64-encoded string

from which you want to generate the
com.wm.util.XOPObject instance.

bytes

byte [ ] Optional. The byte array from

which you want to generate the
com.wm.util.XOPObject instance.

stream

Object Optional. The InputStream

from which you want to generate the
com.wm.util.XOPObject instance.

Output Parameters
xopObject

Object Conditional. An instance of com.wm.util.XOPObject

generated from the input data.
The value of xopObject will be null if you do not specify any
value for the data input parameter.

Usage Notes
You use the object of type com.wm.util.XOPObject to send or receive data as an MTOM
stream. For more information about MTOM streaming, see Web Services Developers
Guide.
If you specify values for more than one key of the data input parameter, Integration
Server uses only one value in the following order or precedence:
base64String
bytes
stream
For example, if you provide values for base64String , bytes , and stream keys, Integration
Server will execute the pub.soap.utils:createXOPObject service with the base64String value
and will ignore the values provided for bytes and stream keys.

pub.soap.utils:exitUnableToUnderstand
WmPublic. Terminates processing and returns a mustUnderstand fault to the client.
You execute this service when your SOAP processor detects a mandatory header entry
that it cannot process.

webMethods Integration Server Built-In Services Reference Version 9.6

789

Even Header
SOAP Folder

Input Parameters
headerEntry

com.wm.lang.xml.Node XML node containing the header entry

that cannot be understood.

Output Parameters
None.
Usage Notes
This service throws an exception, which is meant to be caught by the message handler so
that the appropriate SOAP fault will be returned to the client. Your processor should not
catch this exception.

pub.soap.utils:getActor
WmPublic. Retrieves the value of the actor aribute (for SOAP 1.1) or the role aribute
(for SOAP 1.2) from a given header entry.
Input Parameters
headerEntry

com.wm.lang.xml.Node The header entry whose actor value you

want to retrieve.
If you use pub.soap.utils:getHeaderEntries to retrieve header
entries, you can loop over the list of header nodes to retrieve
the actor value from each entry.
If you use pub.soap.utils:getHeader to retrieve header entries,
you must query the node returned by that service (using
the pub.xml:queryXMLNode service) to extract a node for an
individual header entry. Then you can run getActor on the
resulting node.

Output Parameters
actor

String Value of the header entry's actor aribute (for SOAP

1.1) or the role aribute (for SOAP 1.2). If the header entry
does not have an actor aribute, actor will be null.

See Also
pub.soap.utils:addHeaderEntry
pub.soap.utils:getMustUnderstand
webMethods Integration Server Built-In Services Reference Version 9.6

790

Odd Header
SOAP Folder

pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries

pub.soap.utils:getBody
WmPublic. Retrieves the body from a SOAP message as a single node object.
Input Parameters
soapData

Object SOAP object containing the message whose Body node

you want to retrieve.

Output Parameters
body

com.wm.lang.xml.Node The Body node from the SOAP message

(that is, <SOAP-ENV:Body> to </SOAP-ENV:Body>).

Usage Notes
This service returns the entire Body element in body. To extract data from the Body
element, query body with the pub.xml:queryXMLNode service.
If you want to extract the body of the message as an array of nodes, use the
pub.soap.utils:getBodyEntries service.
See Also
pub.soap.utils:getBodyEntries
pub.soap.utils:addBodyEntry
Examples
See the following in the WmSamples packages in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.soap:buildMsg_sendHTTP
sample.soap:customProc_msgQueue
sample.soap:targetSvc_defaultProc

pub.soap.utils:getBodyEntries
WmPublic. Retrieves the body entries from a SOAP message as an array of node objects.

webMethods Integration Server Built-In Services Reference Version 9.6

791

Even Header
SOAP Folder

Input Parameters
soapData

Object The SOAP object containing the message whose body

entries you want to retrieve.

Output Parameters
bodyEntries

com.wm.lang.xml.Node[ ] An array of XML nodes, where each

node represents a body entry from the message.

Usage Notes
This service returns each body entry as a separate node. You can loop over bodyEntries
and extract data from each node with the pub.xml:queryXMLNode service.
If you want to extract the body of the message as a single node, use the
pub.soap.utils:getBody service.
See Also
pub.soap.utils:getBody
pub.soap.utils:addBodyEntry

pub.soap.utils:getDocument
WmPublic. Retrieves an entire SOAP message as a node object.
This service is useful when you want to use pub.xml:queryXMLNode to query an entire
SOAP message. Since queryXMLNode requires a node as input, you cannot use it to query
a SOAP object directly. Instead, you must convert the SOAP object to a node and then
query the resulting node.
Input Parameters
soapData

Object SOAP object for which you want a node representation.

Output Parameters
node

com.wm.lang.xml.Node Node representation of the entire SOAP

message in soapData (that is, <SOAP-ENV:Envelope> to </
SOAP-ENV:Envelope>.

webMethods Integration Server Built-In Services Reference Version 9.6

792

Odd Header
SOAP Folder

See Also
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries
pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries
pub.soap.utils:getTrailers

pub.soap.utils:getEncoding
WmPublic. Retrieves the encoding from a SOAP message as a single string.
Input Parameters
soapData

Object SOAP object containing the message whose encoding

you want to retrieve.

Output Parameters
encoding

com.wm.lang.xml.Node Encoding from the SOAP message.

See Also
pub.soap.utils:getHeaderEntries
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries
"pub.soap.utils:getDocument" on page 792
pub.soap.utils:getTrailers
pub.soap.utils:addHeaderEntry

pub.soap.utils:getHeader
WmPublic. Retrieves the header from a SOAP message as a single node object.
Input Parameters
soapData

Object SOAP object containing the message whose Header

node you want to retrieve.

webMethods Integration Server Built-In Services Reference Version 9.6

793

Even Header
SOAP Folder

Output Parameters
header

com.wm.lang.xml.Node Header node from the SOAP message

(that is, <SOAP-ENV:Header> to </SOAP-ENV:Header>).

Usage Notes
This service returns the entire Header element in header. To extract data from the Header
element, query header with the pub.xml:queryXMLNode service. If you want to extract the
contents of the header as an array of nodes, use the pub.soap.utils:getHeaderEntries service.
See Also
pub.soap.utils:getHeaderEntries
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries
pub.soap.utils:getTrailers
pub.soap.utils:addHeaderEntry
Examples
See the following in the WmSamples package in the certied samples area of
the Knowledge Center on the Empower Product Support website at hps://
empower.softwareag.com:
sample.soap:customProc_msgQueue

pub.soap.utils:getHeaderEntries
WmPublic. Retrieves the header entries from a SOAP message as an array of node
objects.
This service is useful when you want to build a process that loops through all the
header entries in a message and identify entries with specic QNames (using the
pub.soap.utils:getQName service) or actor aributes (using the pub.soap.utils:getActor service).
Input Parameters
soapData

Object SOAP object containing the message whose header

entries you want to retrieve.

webMethods Integration Server Built-In Services Reference Version 9.6

794

Odd Header
SOAP Folder

Output Parameters
headerEntries

com.wm.lang.xml.Node[ ] Header entries from the SOAP

message. Each node in the array represents a header entry
from the message.

Usage Notes
This service returns each header entry as a separate node. You can loop over
headerEntries and extract data from each node with the pub.xml:queryXMLNode service
or get the entry's QName and/or actor value using the pub.soap.utils:getQName and
pub.soap.utils:getActor services.
If you want to extract the message header as a single node, use the pub.soap.utils:getHeader
service.
See Also
pub.soap.utils:getHeader
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries
pub.soap.utils:getDocument
pub.soap.utils:addHeaderEntry
pub.soap.utils:getActor
pub.soap.utils:getQName

pub.soap.utils:getMustUnderstand
WmPublic. Returns the mustUnderstand status for a given header entry.
The mustUnderstand status species whether recipients are required to process a header
entry (that is, whether processing of the entry is mandatory or optional). Recipients that
cannot process a mandatory header entry must reject the message and return a SOAP
fault. (See the pub.soap.utils:exitUnableToUnderstand service.)
Input Parameters
headerEntry

com.wm.lang.xml.Node The header entry whose mustUnderstand

status you want to retrieve.
If you use pub.soap.utils:getHeaderEntries to retrieve header
entries, you can loop over the list of header nodes to check
the status of each entry.
If you use pub.soap.utils:getHeader to retrieve header entries,
you will need to query the node returned by that service
(using the pub.xml:queryXMLNode service) to extract a

webMethods Integration Server Built-In Services Reference Version 9.6

795

Even Header
SOAP Folder

node for an individual header entry. Then you can run

pub.soap.utils:getMustUnderstand on the resulting node.
Output Parameters
mustUnderstand

String Header entry's mustUnderstand status. If the header

entry has a mustUnderstand aribute, mustUnderstand will
return one of the following values:
0 indicates that the header is optional.
1 indicates that the header is mandatory.
If the header entry does not have a mustUnderstand aribute,
mustUnderstand will return 0.

Usage Notes
For additional information about the mustUnderstand aribute, see the Simple Object
Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 at hp://www.w3.org/TR/SOAP/
and for SOAP 1.2, see the SOAP 1.2 W3C Recommendation 27 April 2007 at hp://
www.w3.org/TR/soap12-part1/.
See Also
pub.soap.utils:addHeaderEntry
pub.soap.utils:getActor
pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries
pub.soap.utils:exitUnableToUnderstand

pub.soap.utils:getQName
WmPublic. Returns the qualied name for a given node.
Input Parameters
node

com.wm.app.b2b.server.saaj.SOAPElement The XML node whose

qualied name you want to discover.

Output Parameters
Qname

Document The node's qualied name.Qname will contain the

following keys:

webMethods Integration Server Built-In Services Reference Version 9.6

796

Odd Header
SOAP Folder

Key

Description

namespaceName

String Namespace portion of the node's

qualied name.

localName

String Local portion of the node's

qualied name.

Usage Notes
Generally, you use this service in conjunction with the pub.soap.utils:getHeaderEntries or
pub.soap.utils:getBodyEntries service to loop over the message's header or body entries and
identify entries with a particular qualied name.
See Also
pub.soap.utils:getBodyEntries
pub.soap.utils:getHeaderEntries

pub.soap.utils:getTrailers
WmPublic. Retrieves the trailers from a SOAP message.
(A trailer is an arbitrary element that follows the Body element in the SOAP envelope.)
Important: It appears likely that trailers will not be permied in future versions of SOAP
(versions 1.2 and later). If you are designing a completely new solution, we recommend
that you avoid using trailers. However, if you exchange SOAP messages with older
systems that already make use of trailers, this service allows you to retrieve them from a
SOAP message.
Input Parameters
soapData

Object SOAP object containing the message whose trailers you

want to retrieve.

Output Parameters
trailers

com.wm.lang.xml.Node[ ] Array of nodes wherein each node

represents a trailer from the message. If the message does not
contain trailers, trailers will be null.

See Also
pub.soap.utils:addTrailer
webMethods Integration Server Built-In Services Reference Version 9.6

797

Even Header
SOAP Folder

pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries
pub.soap.utils:getDocument

pub.soap.utils:getXOPObjectContent
WmPublic. Retrieves the contents of a com.wm.util.XOPObject instance as a
base64Binary string, a byte array, or an InputStream.
Input Parameters
xopObject

Object Optional. The object of type com.wm.util.XOPObject.

getAs

String Optional. The object type in which you want to retrieve

the contents in the com.wm.util.XOPObject instance.
Select...

To...

base64String

Default. Retrieve the contents of the

com.wm.util.XOPObject instance as a
base64-encoded string.

bytes

Retrieve the contents of the

com.wm.util.XOPObject instance as a byte
array.

stream

Retrieve the contents of the

com.wm.util.XOPObject instance as an
InputStream.

Output Parameters
contentType

String Conditional. MIME type of the contents in the input

com.wm.util.XOPObject instance. The contentType parameter
is returned only if you have specied a value for the
xopObject input parameter.

data

Document Contents of the input com.wm.util.XOPObject

instance.

webMethods Integration Server Built-In Services Reference Version 9.6

798

Odd Header
SOAP Folder

If the xopObject input parameter is null, this parameter has a

null value.
Value

Description

base64String

String Conditional. Returns the contents of

the com.wm.util.XOPObject instance as a
base64-encoded string if the getAs input
parameter is set to base64String.

bytes

byte [] Conditional. Returns the contents of

the com.wm.util.XOPObject instance as a
byte array if the getAs input parameter is
set to bytes.

stream

Object Conditional. Returns the contents of

the com.wm.util.XOPObject instance as an
InputStream if the getAs input parameter
is set to stream.

Usage Notes
You use the object of type com.wm.util.XOPObject to send or receive data as an MTOM
stream. For more information about MTOM streaming, see Web Services Developers
Guide.
The content of the XOPObject can only be read one time. After you use the
pub.soap.utils:getXOPObjectContent service to read the XOPObject content one time,
subsequent aempts to re-read the XOPObject content will fail. It is recommended that
after the XOPObject content is read that you drop it from the pipeline to make it clear to
programming logic downstream that it is no longer available to be read.
When you set the getAs input parameter to stream so that the service
returns the contents of the com.wm.util.XOPObject instance as a stream, the
pub.soap.utils:getXOPObjectContent service does not automatically close the stream object.
You can close the stream using the pub.io:close service.

pub.soap.utils:QName
WmPublic. Document type that denes the structure of a qualied name.
Parameters
namespaceName

String The namespace portion of a qualied name.

webMethods Integration Server Built-In Services Reference Version 9.6

799

Even Header
SOAP Folder

localName

String The local portion of a qualied name.

pub.soap.utils:removeBodyEntry
WmPublic. Deletes a body entry from a SOAP message.
Input Parameters
soapData

Object SOAP object containing the body entry that you want to
delete.

bodyEntry

com.wm.lang.xml.Node Optional. The entry that you want to

remove from soapData . (You would obtain the node with the
pub.soap.utils:getBodyEntries service.)
Note: You can use bodyEntry or index to specify the entry that
you want removeBodyEntry to delete.

index

String Optional. Index of the entry that you want to remove

(where index 0 represents the rst body entry). index is
ignored if bodyEntry is specied.

Output Parameters
None.
Usage Notes
When you use the bodyEntry parameter, be sure that it species the correct node. This
service deletes whatever node is specied in bodyEntry , even if the node is not a body
entry. For example, if bodyEntry contains the whole Body element, removeBodyEntry will
delete the body of the message.
Be aware that if you use the index parameter to delete an entry, you will change the
index numbers (positions) of all entries following the one you deleted. For example,
if your message contains four body entries (0, 1, 2, 3) and you delete entry 1, then the
entries originally at positions 2 and 3 will subsequently occupy positions 1 and 2.
See Also
pub.soap.utils:removeHeaderEntry
pub.soap.utils:removeTrailer
pub.soap.utils:addBodyEntry
pub.soap.utils:getBody
pub.soap.utils:getBodyEntries

webMethods Integration Server Built-In Services Reference Version 9.6

800

Odd Header
SOAP Folder

pub.soap.utils:removeHeaderEntry
WmPublic. Deletes a header entry from a SOAP message.
Input Parameters
soapData

Object SOAP object containing the header entry that you want
to delete.

headerEntry

com.wm.lang.xml.Node Optional. The header entry that you want

to remove from soapData . (You would obtain the node with
the pub.soap.utils:getHeaderEntries service.)
Note: You can use headerEntry or index to specify the entry that
you want removeHeaderEntry to delete.

index

String Optional. Index of the entry that you want to remove

(where index 0 represents the rst header entry). index is
ignored if headerEntry is specied.

Output Parameters
None.
Usage Notes
When you use the headerEntry parameter, be sure that it species the correct node. This
service deletes whatever node is specied in headerEntry , even if the node is not a header
entry. For example, if headerEntry contains the whole Header element, removeHeaderEntry
will delete the entire header from the message.
Note: Be aware that if you use the index parameter to delete an entry, you will change
the index numbers (positions) of all entries following the one you deleted. For example,
if your header contains four entries (0, 1, 2, 3) and you delete entry 1, then the entries
originally at positions 2 and 3 will subsequently occupy positions 1 and 2.
See Also
pub.soap.utils:removeBodyEntry
pub.soap.utils:removeTrailer
pub.soap.utils:addHeaderEntry
pub.soap.utils:getHeader
pub.soap.utils:getHeaderEntries

webMethods Integration Server Built-In Services Reference Version 9.6

801

Even Header
SOAP Folder

pub.soap.utils:removeTrailer
WmPublic. Deletes a trailer from a SOAP message.
Input Parameters
soapData

Object SOAP object containing the trailer that you want to

delete.

trailer

com.wm.lang.xml.Node Optional. The trailer that you want to

remove from soapData . (You would obtain the node with the
pub.soap.utils:getTrailers service.)
Note: You can use trailer or index to specify the trailer that you
want removeTrailer to delete.

index

StringOptional. Index of the trailer that you want to remove

(where index 0 represents the rst trailer). index is ignored if
trailer is specied.

Output Parameters
None.
Usage Notes
When you use the trailer parameter, be sure that it species the correct node. This
service deletes whatever node is specied in trailer , even if the node is not a trailer. For
example, if trailer contains the Body element, removeTrailer will delete the entire body of
the message.
Note: Be aware that if you use the index parameter to delete a trailer, you will change the
index numbers (positions) of all trailers following the one you deleted. For example, if
your message contains four trailers (0, 1, 2, 3) and you delete trailer 1, then the trailers
originally at positions 2 and 3 will subsequently occupy positions 1 and 2.
See Also
pub.soap.utils:removeHeaderEntry
pub.soap.utils:removeBodyEntry
pub.soap.utils:addTrailer
pub.soap.utils:getTrailers

webMethods Integration Server Built-In Services Reference Version 9.6

802

Odd Header
SOAP Folder

pub.soap.utils:requestResponseSpec
WmPublic. Denes the input/output signature for a custom processor and a target
service for the default processor.
Input Parameters
soapRequestData

Object SOAP object containing the SOAP request submied to

the Integration Server by the client.

soapResponseData

Object Empty SOAP object that the custom processor or target

service uses to compose the SOAP response message.

Output Parameters
soapResponseData

Object SOAP object containing the message that is to be

returned to the client.

pub.soap.utils:resetWSDEffectivePolicy
WmPublic. Returns the eective policy for a handler in a web service descriptor to the
policy set in the Policy name property in Software AG Designer.
Input Parameters
wsdName

String The name of the web service descriptor for which you
want to reset the eective policy.
Note: The resetWSDEffectivePolicy service applies only to web
services that run in pre-8.2 compatibility mode (i.e., the Pre-8.2
compatibility mode property is set to true).

handlerName

String The name of the handler for which you want to reset the
eective policy.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

803

Even Header
SOAP Folder

Usage Notes
You can also use Designer to reset the eective policy. In Designer, open the web service
descriptor, select the handler on the Handlers view, and modify the value of Effective
policy name property assigned to the handler.
The pub.soap.utils:resetWSDEffectivePolicy service throws an exception if the provided inputs
are invalid.
See Also
pub.soap.utils.setWSDEffectivePolicy

pub.soap.utils.setWSDEffectivePolicy
WmPublic. Sets the eective policy for a handler in a web service descriptor.
Input Parameters
wsdName

String The name of the web service descriptor for which you
want to set the eective policy.
The setWSDEffectivePolicy service applies only to web services that
run in pre-8.2 compatibility mode (i.e., the Pre-8.2 compatibility
mode property is set to true).

handlerName

String The name of the handler for which you want to set the
eective policy.

eectivePolicyID

String The unique identier for the policy that you want to use
with the handler in the web service descriptor.

Output Parameters
None.
Usage Notes
The pub.soap.utils.setWSDEffectivePolicy service overrides the policy originally assigned to
the handler in the web service descriptor.
The pub.soap.utils.setWSDEffectivePolicy service applies to provider web service descriptors
as well as consumer web service descriptors.
The pub.soap.utils.setWSDEffectivePolicy service throws an exceptions if the provided input is
incorrect. The service also veries that the provided eective policy actually exists.

webMethods Integration Server Built-In Services Reference Version 9.6

804

Odd Header
SOAP Folder

You can also use Designer to set the eective policy. In Designer, open the web service
descriptor, select the handler in the Handlers view, and modify the value of Effective policy
name property assigned to the handler.
You can reset the eective policy using the pub.soap.utils:resetWSDEffectivePolicy service.
See Also
pub.soap.utils:resetWSDEffectivePolicy

pub.soap.utils:soapDataToBytes
WmPublic. Converts a SOAP object to a Byte Array.
This is useful when you want to use the message with a process that requires the
message to be in the form of a Byte Array.
Input Parameters
soapData

Object SOAP object that you want to convert to a Byte Array.

Output Parameters
bytes

Object Entire SOAP message.

See Also
pub.soap.utils:soapDataToString
pub.soap.utils:streamToSoapData
pub.soap.utils:stringToSoapData

pub.soap.utils:soapDataToString
WmPublic. Converts a SOAP object to a String.
This is useful when you want to use the message with a process that requires the
message to be in the form of a String.
Input Parameters
soapData

Object SOAP object that you want to convert to a String.

webMethods Integration Server Built-In Services Reference Version 9.6

805

Even Header
SOAP Folder

Output Parameters
string

String Entire SOAP message.

See Also
pub.soap.utils:soapDataToBytes
pub.soap.utils:streamToSoapData
pub.soap.utils:stringToSoapData

pub.soap.utils:soapFault
WmPublic. Document type that denes the generic SOAP fault structure used by web
service descriptors created in Integration Server 8.2 and later.
Parameters
code

Document Contains the fault code and possible subcodes.

Key

Description

namespaceName

String Optional. Namespace name for the SOAP

fault code.

localName

String Code that identies the fault.

subCodes

Document List Optional. Subcodes that provide

further detail. Each Document in the subCodes
Document List contains:
namespaceName for the subcode
localName that identies the subcode

reasons

Document List Reasons for the SOAP fault. Each Document in the
Document List contains a human readable explanation of the
cause of the fault.
Key

Description

*body

String Text explaining the cause of the fault.

webMethods Integration Server Built-In Services Reference Version 9.6

806

Odd Header
SOAP Folder

String Optional. Language for the human

readable description.

@lang
node

String Optional. URI to the SOAP node where the fault occurred.

role

String Optional. Role in which the node was operating at the point
the fault occurred.

detail

Document Optional. Application-specic details about the SOAP

fault.

pub.soap.utils:streamToSoapData
WmPublic. Converts an InputStream containing a SOAP message to a SOAP object.
(A SOAP message must be represented as a SOAP object to be used with the dataretrieval services such as pub.soap.utils:getHeader and pub.soap.utils:getBody).
Note: This service is a convenient way to produce a SOAP object during development
and testing. It is not meant to be used for production purposes because it does not ensure
that a valid SOAP message is produced. For production purposes, we recommend that
you create SOAP objects with the pub.soap.utils:createSoapData service and populate them
with the message-composition services (for example, pub.soap.utils:addBodyEntry and
pub.soap.utils:addHeaderEntry).
Input Parameters
stream

java.io.InputStream SOAP message that is to be converted to a

SOAP object.

soapProtocol

String Optional. Indicates the SOAP protocol that the resulting

SOAP object will work with. The default value is read from the
wa.server.SOAP.defaultProtocol property. Set to:
SOAP 1.1 Protocol to indicate the SOAP object works with

SOAP 1.1.

SOAP 1.2 Protocol to indicate the SOAP object works with

SOAP 1.2.
Output Parameters
soapData

Object SOAP object representation of the SOAP message in

stream .

webMethods Integration Server Built-In Services Reference Version 9.6

807

Even Header
SOAP Folder

Usage Notes
Be aware that if stream does not contain a valid SOAP message, this service does not
throw an exception. Instead, it produces a soapData that contains a representation of
whatever it received in stream (which might not even be an XML document). This will
cause problems later when you aempt to use the soapData with other SOAP utilities or
pass it to the message handler. To determine whether soapData represents a valid SOAP
message, we recommend that you always execute the pub.soap.utils:validateSoapData service
immediately after using streamToSoapData.
See Also
pub.soap.utils:soapDataToBytes
pub.soap.utils:stringToSoapData
pub.soap.utils:validateSoapData

pub.soap.utils:stringToSoapData
WmPublic. Converts a String containing a SOAP message to a SOAP object.
(A SOAP message must be represented as a SOAP object to be used with the dataretrieval services such as pub.soap.utils:getHeader and pub.soap.utils:getBody).
Note: This service is a convenient way to produce a SOAP object during development
and testing. It is not meant to be used for production purposes because it does not ensure
that a valid SOAP message is produced. Additionally, producing a SOAP object from a
String is a very time-consuming process. For production purposes, we recommend that
you create SOAP objects with the such as pub.soap.utils:getHeader and pub.soap.utils:getBody).
Input Parameters
string

String SOAP message that is to be converted to a SOAP object.

soapProtocol

String Optional. Indicates the SOAP protocol that the resulting

SOAP object will work with. The default value is read from the
wa.server.SOAP.defaultProtocol property. Set to:
SOAP 1.1 Protocol to indicate the SOAP object works with

SOAP 1.1.

SOAP 1.2 Protocol to indicate the SOAP object works with

SOAP 1.2.
addEmptyHeader

String Optional. Species whether to create an empty header

entry along with the SOAP envelope and body entries in the
SOAP message. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

808

Odd Header
SOAP Folder

True to create an empty header entry in the SOAP message.

False to create only the SOAP envelope and body entries.

This seing overrides the global

wa.server.SOAP.addEmptyHeader seing of Integration
Server.
Important: There is no default value. If you do not specify a
value for the addEmptyHeader parameter, the service uses the
value specied in the wa.server.SOAP.addEmptyHeader
server conguration parameter. For more information
about wa.server.SOAP.addEmptyHeader, see webMethods
Integration Server Administrators Guide.
Output Parameters
soapData

Object SOAP object representation of the SOAP message in

string .

See Also
pub.soap.utils:soapDataToBytes
pub.soap.utils:streamToSoapData
pub.soap.utils:validateSoapData

pub.soap.utils:validateSoapData
WmPublic. Veries that a SOAP object represents a valid SOAP message.
You can use this service to validate a SOAP object that was generated directly from an
InputStream or String with pub.soap.utils:stringToSoapData or pub.soap.utils:streamToSoapData.
If soapData does not contain a valid SOAP message, validateSoapData will throw an
exception.
This service validates the SOAP object against the schema in pub.soap.schema:envelope.
Input Parameters
soapData

Object SOAP object that you want to validate.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

809

Even Header
SOAP Folder

Usage Notes
If you create SOAP objects using the standard message-composition services (for
example, pub.soap.utils:createSoapData, pub.soap.utils:addBodyEntry, pub.soap.utils:addHeaderEntry)
there is no need to use this service. This service is only necessary when you generate a
SOAP object directly from an InputStream or a String.
When validating SOAP, Integration Server uses the W3C recommendation XML Schema
Part 2: Datatypes. If you want to validate the input of this service for illegal values in the
SOAP envelope and header, set the wa.core.validation.w3cConformant conguration
parameter to true. For information about seing this conguration parameter, see
webMethods Integration Server Administrators Guide.
See Also
pub.soap.utils:stringToSoapData
pub.soap.utils:streamToSoapData

pub.soap.wsa:action
WmPublic. Document type that denes the contents of the wsa:Action WS-Addressing
header.
Parameters
wsa:Action

Document Contains the WS-Addressing action.

Key

Description

*body

String Value of the WS-Addressing action.

Usage Notes
To add, retrieve, or remove the wsa:Action header of a SOAP message,
use pub.soap.wsa:action as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:faultTo
WmPublic. Document type that denes the contents of the wsa:FaultTo WSAddressing header.

webMethods Integration Server Built-In Services Reference Version 9.6

810

Odd Header
SOAP Folder

Parameters
wsa:FaultTo

Document Contains the address of the intended receiver of the fault

message.
Key

Description

wsa:Address

Document Contains the end point URI for the fault

message.

wsa:Reference
Parameters

wsa:Metadata

*any

Key

Description

*body

String The end point URI for

the fault message.

Document Contains the set of reference parameter

elements.
Key

Description

*any

Object List The reference

parameter elements.

Document Contains the set of metadata elements.

Key

Description

*any

Object List The metadata

elements.

Object List Contains other extensible elements, if

any.

Usage Notes
To add, retrieve, or remove the wsa:FaultTo header of a SOAP message,
use pub.soap.wsa:faultTo as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

811

Even Header
SOAP Folder

pub.soap.wsa:from
WmPublic. Document type that contains the details of the source of the message.
Parameters
wsa:From

Document Contains the details about the source of the message.

Key

Description

wsa:Address

Document Contains the address of the source of the

message.

wsa:Reference
Parameters

wsa:Metadata

*any

Key

Description

*body

String The address of the

source of the message.

Document Contains the set of reference parameter

elements.
Key

Description

*any

Object List The reference

parameter elements.

Document Contains the set of metadata elements.

Key

Description

*any

Object List The metadata

elements.

Object List Contains other extensible elements, if

any.

Usage Notes
To add, retrieve, or remove the wsa:From header of a SOAP message,
use pub.soap.wsa:from as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.

webMethods Integration Server Built-In Services Reference Version 9.6

812

Odd Header
SOAP Folder

For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:messageID
WmPublic. Document type that denes the contents of the wsa:MessageID WSAddressing header.
Parameters
wsa:MessageID

Document Unique identier of the SOAP message.

Key

Description

*body

String The unique identier of the SOAP

message.

Usage Notes
To add, retrieve, or remove thewsa:MessageID header of a SOAP message,
use pub.soap.wsa:messageID as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:problemAction
WmPublic. Document type that captures additional information about faults.
Parameters
wsa:ProblemAction

Document Contains additional information about faults.

Key

Description

wsa:Action

Document Optional. Element that provides

the details about the [action] that caused the
problem.
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

813

Even Header
SOAP Folder

*body

String Optional. The [action]

that caused the problem.

wsa:SoapAction String Optional. Element that contains the

SOAPAction IRI that caused the problem.
Usage Notes
To add, retrieve, or remove the wsa:ProblemAction header of a SOAP
message, use pub.soap.wsa:problemAction as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:problemHeaderQName
WmPublic. Document type that captures additional information about faults.
Parameters
wsa:ProblemHeader
QName

Document Contains additional information about faults.

Key

Description

*body

String Optional. The QName representing the

name of the root element of the problem header
block.

Usage Notes
To add, retrieve, or remove the wsa:ProblemHeaderQName header of a SOAP
message, use pub.soap.wsa:problemHeaderQName as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:problemIRI
WmPublic. Document type that captures the IRI that caused the problem.

webMethods Integration Server Built-In Services Reference Version 9.6

814

Odd Header
SOAP Folder

Parameters
wsa:ProblemIRI

Document Contains the IRI that caused the problem.

Key

Description

*body

String Optional. The string representing the IRI

that caused the problem.

Usage Notes
To add, retrieve, or remove the wsa:ProblemIRI header of a SOAP message,
use pub.soap.wsa:problemIRI as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:relatesTo
WmPublic. Document type that denes the contents of the wsa:RelatesTo WSAddressing header.
Parameters
wsa:RelatesTo

Document Contains the relationship information.

Key

Description

@Relationship
Type

String Optional. The relationship type.

*body

String<wsa:MessageID> of the related SOAP

message.

Usage Notes
To add, retrieve, or remove the wsa:RelatesTo header of a SOAP message,
use pub.soap.wsa:relatesTo as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.

webMethods Integration Server Built-In Services Reference Version 9.6

815

Even Header
SOAP Folder

For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:replyTo
WmPublic. Document type that denes the contents of the wsa:ReplyTo WSAddressing header.
Parameters
wsa:ReplyTo

Document Contains the address of the intended receiver of the

response message.
Key

Description

wsa:Address

Document Contains the end point URI for the

response message.

wsa:Reference
Parameters

wsa:Metadata

*any

Key

Description

*body

String Optional. The end

point URI for the response
message.

Document Optional. Contains the set of reference

parameter elements.
Key

Description

*any

Object List Optional. The

reference parameter
elements.

Document Optional. Contains the set of metadata

elements.
Key

Description

*any

Object List Optional. The

metadata elements.

Object List Optional. Contains other extensible

elements, if any.

webMethods Integration Server Built-In Services Reference Version 9.6

816

Odd Header
SOAP Folder

Usage Notes
To add, retrieve, or remove the wsa:ReplyTo header of a SOAP message,
use pub.soap.wsa:replyTo as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:retryAfter
WmPublic. Document type that you can use to retrieve the wsa:RetryAfter header of a
SOAP message.
Parameters
wsa:RetryAfter

Document Contains the wsa:RetryAfter header of a SOAP

message.
Key

Description

*body

String Optional. The retry after duration

retrieved from the wsa:RetryAfter SOAP
header.

Usage Notes
To add, retrieve, or remove the wsa:RetryAfter header of a SOAP message,
use pub.soap.wsa:retryAfter as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:to
WmPublic. Document type that denes the contents of the wsa:To WS-Addressing
header.

webMethods Integration Server Built-In Services Reference Version 9.6

817

Even Header
SOAP Folder

Parameters
wsa:To

Document Contains the address of the intended receiver of the

message.
Key

Description

*body

String The address of the intended receiver of

the message.

Usage Notes
To add, retrieve, or remove the wsa:To header of a SOAP message, use pub.soap.wsa:to
as the value for the documentType input parameter of the pub.soap.handler:addHeaderBlock,
pub.soap.handler:getHeaderBlock, and pub.soap.handler:removeBodyBlock services.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa:schema_wsa
WmPublic. A schema containing the elements from http://www.w3.org/2005/08/
addressing namespace.

pub.soap.wsa.submission:action
WmPublic. Document type that denes the contents of the wsa:Action WS-Addressing
header.
Parameters
wsa:Action

Document Contains the WS-Addressing action.

Key

Description

*body

String Value of the WS-Addressing action.

Usage Notes
To add, retrieve, or remove the wsa:Action header of a SOAP message,
use pub.soap.wsa.submission:action as the value for the documentType input

webMethods Integration Server Built-In Services Reference Version 9.6

818

Odd Header
SOAP Folder

parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and

pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:action document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:faultTo
WmPublic. Document type that denes the contents of the wsa:FaultTo WSAddressing header.
Parameters
wsa:FaultTo

Document Contains the address of the intended receiver of the fault

message.
Key

Description

wsa:Address

Document Contains the end point URI for the fault

message.

wsa:Reference
Properties

wsa:Reference
Parameters

Key

Description

*body

String Optional. The end

point URI for the fault
message.

Document Optional. The properties that are

required to identify the entity or resource being
conveyed.
Key

Description

*any

Object List Optional. The

property elements.

Document Optional. Contains the set of reference

parameter elements.
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

819

Even Header
SOAP Folder

*any

wsa:PortType

wsa:Service
Name

*any

Object List Optional. The

reference parameter
elements.

Document Optional. Contains the QName of

the primary portType of the endpoint being
conveyed.
Key

Description

*body

Object List Optional. The

QName of the primary
portType of the endpoint
being conveyed.

Document Optional. Represents the QName

identifying the WSDL service element that
contains the denition of the endpoint being
conveyed.
Key

Description

@PortName

String Optional. The name of

the <wsdl:port> denition
that corresponds to the
endpoint being referenced.

*body

String Optional. The

<wsdl:service> denition
that contains a WSDL
description of the endpoint
being referenced.

Object List Optional. Contains other extensible

elements, if any.

Usage Notes
To add, retrieve, or remove the wsa:FaultTo header of a SOAP message,
use pub.soap.wsa.submission:faultTo as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:faultTo document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.

webMethods Integration Server Built-In Services Reference Version 9.6

820

Odd Header
SOAP Folder

For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:from
WmPublic. Document type that contains the details about the source of the message.
Parameters
wsa:From

Document Contains the details about the source of the message.

Key

Description

wsa:Address

Document Contains the details about the source of

the message.

wsa:Reference
Properties

wsa:Reference
Parameters

wsa:PortType

Key

Description

*body

String Optional. The address

of the source of the message.

Document Optional. The properties that are

required to identify the entity or resource being
conveyed.
Key

Description

*any

Object List Optional. The

property elements.

Document Optional. Contains the set of reference

parameter elements.
Key

Description

*any

Object List Optional. The

reference parameter
elements.

Document Optional. Contains the QName of

the primary portType of the endpoint being
conveyed.

webMethods Integration Server Built-In Services Reference Version 9.6

821

Even Header
SOAP Folder

wsa:Service
Name

Key

Description

*body

Object List Optional. The

QName of the primary
portType of the endpoint
being conveyed.

Document Optional. Represents the QName

identifying the WSDL service element that
contains the denition of the endpoint being
conveyed.
Key

Description

@PortName

String Optional. The name of

the <wsdl:port> denition
that corresponds to the
endpoint being referenced.

*body

String Optional. The

<wsdl:service> denition

that contains a WSDL

description of the endpoint
being referenced.

*any

Object List Optional. Contains other extensible

elements, if any.

Usage Notes
To add, retrieve, or remove the wsa:From header of a SOAP message, use
pub.soap.wsa.submission:from as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:from document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:messageID
WmPublic. Document type that denes the contents of the wsa:MessageID WSAddressing header.

webMethods Integration Server Built-In Services Reference Version 9.6

822

Odd Header
SOAP Folder

Parameters
wsa:MessageID

Document Unique identier of the SOAP message.

Key

Description

*body

String The unique identier of the SOAP

message.

Usage Notes
To add, retrieve, or remove the wsa:MessageID header of a SOAP message,
use pub.soap.wsa.submission:messageID as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:messageID document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:relatesTo
WmPublic. Document type that denes the contents of the wsa:RelatesTo WSAddressing header.
Parameters
wsa:RelatesTo

Document Contains the relationship information.

Key

Description

@RelationshipTypeString Optional. The relationship type.

*body

String<wsa:MessageID> of the related SOAP

message.

Usage Notes
To add, retrieve, or remove the wsa:RelatesTo header of a SOAP message,
use pub.soap.wsa.submission:relatesTo as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.

webMethods Integration Server Built-In Services Reference Version 9.6

823

Even Header
SOAP Folder

The pub.soap.wsa.submission:relatesTo document type relates to the W3C WS-Addressing

Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:replyTo
WmPublic. Document type that species the destination to which the response message
is to be sent.
Parameters
wsa:FaultTo

Document Contains the address of the intended receiver of the

response message.
Key

Description

wsa:Address

Document Contains the end point URI for the

response.

wsa:Reference
Properties

wsa:Reference
Parameters

Key

Description

*body

String Optional. The end

point URI for the fault
message.

Document Optional. The properties that are

required to identify the entity or resource being
conveyed.
Key

Description

*any

Object List Optional. The

property elements.

Document Optional. Contains the set of reference

parameter elements.
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

824

Odd Header
SOAP Folder

*any

wsa:PortType

wsa:Service
Name

Object List Optional. The

reference parameter
elements.

Document Optional. Contains the QName of

the primary portType of the endpoint being
conveyed.
Key

Description

*body

Object List Optional. The

QName of the primary
portType of the endpoint
being conveyed.

Document Optional. Represents the QName

identifying the WSDL service element that
contains the denition of the endpoint being
conveyed.
Key

Description

@PortName

String Optional. The name of

the <wsdl:port> denition
that corresponds to the
endpoint being referenced.

*body

String Optional. The

<wsdl:service> denition

that contains a WSDL

description of the endpoint
being referenced.

*any

Object List Optional. Contains other extensible

elements, if any.

Usage Notes
To add, retrieve, or remove the wsa:ReplyTo header of a SOAP message,
use pub.soap.wsa.submission:replyTo as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:replyTo document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.

webMethods Integration Server Built-In Services Reference Version 9.6

825

Even Header
SOAP Folder

For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:retryAfter
WmPublic. Document type that you can use to retrieve the wsa:RetryAfter header of a
SOAP message.
Parameters
wsa:RetryAfter

Document Contains you can use to retrieve the

wsa:RetryAfter header of a SOAP message.
Key

Description

*body

String Optional. The retry after duration

retrieved from the wsa:RetryAfter SOAP
header.

Usage Notes
To add, retrieve, or remove the wsa:RetryAfter header of a SOAP message,
use pub.soap.wsa.submission:retryAfter as the value for the documentType input
parameter of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:retryAfter document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:to
WmPublic. Document type that denes the contents of the wsa:To WS-Addressing
header.
Parameters
wsa:To

Document Contains the address of the intended receiver of the

message.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

826

Odd Header
SOAP Folder

*body

String The address of the intended receiver of

the message.

Usage Notes
To add, retrieve, or remove the wsa:To header of a SOAP message, use
pub.soap.wsa.submission:to as the value for the documentType input parameter
of the pub.soap.handler:addHeaderBlock, pub.soap.handler:getHeaderBlock, and
pub.soap.handler:removeBodyBlock services.
The pub.soap.wsa.submission:to document type relates to the W3C WS-Addressing
Submission version of WS-Addressing specication.
For more details about how Integration Server implements WS-Addressing, see the
Web Services Developers Guide.

pub.soap.wsa.submission:schema_wsa_submission
WmPublic. A schema containing the elements from http://schemas.xmlsoap.org/
ws/2004/08/addressing namespace.

pub.soap.wsrm:closeSequence
WmPublic. Closes a reliable messaging sequence.
Input Parameters
serverSequenceId

String Unique identier associated with the reliable messaging

sequence that you want to close.
Note: The serverSequenceId parameter is returned as the output
parameter of the pub.soap.wsrm:createSequence service or as the
reliableMessagingInfo/responseReliableMessagingProperties/server
SequenceId output parameter of a web service connector.

Output Parameters
fault

Document Conditional. Contents of the fault block.

The fault document references the pub.soap.utils:soapFault document
type.

transportInfo

Document Conditional. Headers from response and request

messages.

webMethods Integration Server Built-In Services Reference Version 9.6

827

Even Header
SOAP Folder

The contents of transportInfo vary depending on the actual

transport used by the service.
Note: The transport information returned by this service is similar to
the transport information returned by a web service connector. For
more information, see Web Services Developers Guide.
The transportInfo parameter contains the following keys:
Key

Description

requestHeaders

Document Conditional. Header elds

from the request message issued by the
reliable messaging source.

responseHeaders

Document Conditional. Header elds from

the response.
Each key in responseHeaders represents
a eld (line) of the response header.
Key names represent the names of
header elds. The key values are Strings
containing the values of the elds.
Whether or not the service returns the
responseHeaders parameter depends on
the success or failure of the service. In
the case of failure, the point at which the
failure occurs determines the presence of
the responseHeaders parameter.

status

Document Conditional. Status code from

the request.

statusMessage

Document Conditional. Description of the

status code returned by the underlying
transport.

pub.soap.wsrm:createSequence
WmPublic. Sends a request to a reliable messaging destination to create a new reliable
messaging sequence.

webMethods Integration Server Built-In Services Reference Version 9.6

828

Odd Header
SOAP Folder

Input Parameters
consumer
WebService
DescriptorName

String Fully qualied name of the consumer web service descriptor

for which the reliable message sequence is to be created. That is,
the consumer web service descriptor that contains the reliable
messaging destination endpoint information.
Note: The consumer web service descriptor must have a reliable
messaging policy aached or must be created from a reliable
messaging policy annotated WSDL.

_port

String Species the port that Integration Server uses to resolve the
endpoint address with which the reliable messaging sequence is to
be established.

sequenceKey

String Optional. Unique key to identify the message sequence. A

reliable messaging client associates a sequence key to a message
sequence based on the endpoint URL to which the message
sequence is directed. In cases where there are several message
sequences directed to the same endpoint URL, you can specify a
custom sequence key to identify each sequence. Each sequence
is then uniquely identied by the endpoint URL and the userspecied sequence key.
Important: The user-specied sequence key should not exceed 32
characters in length.

acksTo

Document Optional. Consumer response endpoint address

to which the reliable message destination must send the
acknowledgment. To specify the consumer response endpoint
address, use the Response endpoint address template binder property
of the consumer web service descriptor for which the reliable
message sequence is to be created, as the address template and
replace the placeholders <server> and <port> with appropriate
values.
If no address is specied as acksTo , the acknowledgment messages
are sent back to the requester.
Key

Description

address

Document Document specifying the address to

which the acknowledgment is to be sent.
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

829

Even Header
SOAP Folder

value
auth

String Address to which the

acknowledgment is to be sent.

Document Optional. Transport-level credentials to include in the

request. Integration Server uses the information provided in auth
to create the SOAP request.
Note: Information specied in auth overwrites any authentication
credentials specied in the consumer endpoint alias that is assigned
to the binder.
Key

Description

transport

Document Optional. Transport level authorization

parameters to include in the HTTP request.
Integration Server uses the information specied
in the transport variable to populate the
Authorization header in the HTTP request.
You only need to provide credentials in transport
if the endpoint URL species HTTPS and you
want to overwrite the credentials specied in the
consumer endpoint alias assigned to the binder.
Key

Description

type

String Optional. Type of

authentication required by the
reliable messaging client. If
type is not specied, Integration
Server uses Basic.
Note: If any value other than Basic
is specied, Integration Server
ignores the credentials provided
in user , pass , and serverCerts .

user

String Optional. User name

used to authenticate the reliable
messaging client at the HTTP
or HTTPS transport level on the
reliable messaging server.

pass

String Optional. Password used

to authenticate the reliable

webMethods Integration Server Built-In Services Reference Version 9.6

830

Odd Header
SOAP Folder

messaging client to the reliable

messaging server.
serverCerts

Document Optional. The private

key and certicate chain of the
message signer.
keyStoreAlias String Alias to
the keystore that contains
the private key used to
securely connect to the reliable
messaging server.
keyAlias String Alias to the key
in the keystore that contains
the private key used to connect
to the reliable messaging
server securely. The key must
be in the keystore specied in
keyStoreAlias .

timeout

String Optional. Time (in milliseconds) to wait for a response from

the reliable messaging server before timing out and terminating
the request.
If timeout is not specied, or a value less than 0 is
specied, Integration Server uses the value of the
wa.server.SOAP.request.timeout server property.
For more information about server conguration properties, see
webMethods Integration Server Administrators Guide.
A timeout value of 0 means Integration Server waits for a response
indenitely. If the connection to the reliable messaging server ends
before Integration Server receives a response, the service ends
with an exception and a status code of 408.

_url

String Optional. URL to use as the endpoint URL for the web
service. If supplied, the value of _url overwrites the endpoint URL
in the original WSDL.

transportHeaders

Document Optional. Transport header elds that you want to

explicitly set in the request issued by the reliable messaging client.
Specify a key in transportHeaders for each header eld that you
want to set. The key name represents the name of the header eld
and the key value represents the value of that header eld. The
names and values supplied to transportHeaders must be of type
String. For information about using transportHeaders , including

webMethods Integration Server Built-In Services Reference Version 9.6

831

Even Header
SOAP Folder

a description of the default Integration Server behavior, see

Web Services Developers Guide.
Output Parameters
serverSequenceId

String Unique identier returned by Integration Server and

associated with each message sequence.
Note: The serverSequenceId is used as the input parameter of
pub.soap.wsrm:closeSequence, pub.soap.wsrm:sendAcknowledgementRequest,
pub.soap.wsrm:terminateSequence, and
pub.soap.wsrm:waitUntilSequenceCompleted services.

fault

Document Conditional. Contents of the fault block.

The fault document references the "pub.soap.utils:soapFault" on
page 806 document type.

transportInfo

Document Conditional. Headers from response and request

messages.
The contents of transportInfo vary depending on the actual
transport used by the service.
Note: The transport information returned by this service is similar to
the transport information returned by a web service connector. For
more information, see Web Services Developers Guide.
The transportInfo parameter contains the following keys:
Key

Description

requestHeaders

Document Conditional. Header elds from

the request message issued by the reliable
messaging source.

responseHeaders

Document Conditional. Header elds from the

response.
Each key in responseHeaders represents a eld
(line) of the response header. Key names
represent the names of header elds. The key
values are Strings containing the values of the
elds.
Whether or not the service returns the
responseHeaders parameter depends on the
success or failure of the service. In the case of

webMethods Integration Server Built-In Services Reference Version 9.6

832

Odd Header
SOAP Folder

failure, the point at which the failure occurs

determines the presence of the responseHeaders
parameter.
status

Document Conditional. Status code from the

request.

statusMessage

Document Conditional. Description of the status

code returned by the underlying transport.

pub.soap.wsrm:sendAcknowledgementRequest
WmPublic. Requests an acknowledgment for a message sequence.
Input Parameters
serverSequenceId

String Unique identier associated with the reliable messaging

sequence for which you want an acknowledgment.
Note: The serverSequenceId parameter is returned as the output
parameter of the pub.soap.wsrm:createSequence service or as
the reliableMessagingInfo/responseReliableMessagingProperties/
serverSequenceId output parameter of the web service connector.

Output Parameters
fault

Document Conditional. Contents of the fault block.

The fault document references the "pub.soap.utils:soapFault" on
page 806 document type.

transportInfo

Document Conditional. Headers from response and request

messages.
The contents of transportInfo vary depending on the actual
transport used by the service.
Note: The transport information returned by this service is similar to
the transport information returned by a web service connector. For
more information, see Web Services Developers Guide.
The transportInfo parameter contains the following keys:
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

833

Even Header
SOAP Folder

requestHeaders

Document Conditional. Header elds

from the request message issued by the
reliable messaging source.

responseHeaders

Document Conditional. Header elds from

the response.
Each key in responseHeaders represents
a eld (line) of the response header.
Key names represent the names of
header elds. The key values are Strings
containing the values of the elds.
Whether or not the service returns the
responseHeaders parameter depends on
the success or failure of the service. In
the case of failure, the point at which the
failure occurs determines the presence of
the responseHeaders parameter.

status

Document Conditional. Status code from

the request.

statusMessage

Document Conditional. Description of the

status code returned by the underlying
transport.

pub.soap.wsrm:terminateSequence
WmPublic. Terminates a reliable messaging sequence.
Input Parameters
serverSequenceId

String Unique identier associated with the reliable messaging

sequence that you want to terminate.
Note: The serverSequenceId parameter is returned as the output
parameter of the pub.soap.wsrm:createSequence service or as
the reliableMessagingInfo/responseReliableMessagingProperties/
serverSequenceId output parameter of the web service connector.

Output Parameters
fault

Document Conditional. Contents of the fault block.

webMethods Integration Server Built-In Services Reference Version 9.6

834

Odd Header
SOAP Folder

The fault document references the "pub.soap.utils:soapFault" on

page 806 document type.
transportInfo

Document Conditional. Headers from response and request

messages.
The contents of transportInfo vary depending on the actual
transport used by the service.
Note: The transport information returned by this service is similar to
the transport information returned by a web service connector. For
more information, see Web Services Developers Guide.
The transportInfo parameter contains the following keys:
Key

Description

requestHeaders

Document Conditional. Header elds

from the request message issued by the
reliable messaging source.

responseHeaders

Document Conditional. Header elds from

the response.
Each key in responseHeaders represents
a eld (line) of the response header.
Key names represent the names of
header elds. The key values are Strings
containing the values of the elds.
Whether or not the service returns the
responseHeaders parameter depends on
the success or failure of the service. In
the case of failure, the point at which the
failure occurs determines the presence of
the responseHeaders parameter.

status

Document Conditional. Status code from

the request.

statusMessage

Document Conditional. Description of the

status code returned by the underlying
transport.

webMethods Integration Server Built-In Services Reference Version 9.6

835

Even Header
SOAP Folder

pub.soap.wsrm:waitUntilSequenceCompleted
WmPublic. Instructs Integration Server to wait for a reliable messaging sequence to
complete before terminating it.
Input Parameters
serverSequenceId

String Unique identier associated with a reliable messaging

sequence. Integration Server waits for all the messages in the
specied message sequence to be sent and acknowledged before
terminating the sequence.
Note: The serverSequenceId parameter is returned as the output
parameter of the pub.soap.wsrm:createSequence service or as
the reliableMessagingInfo/responseReliableMessagingProperties/
serverSequenceId output parameter of the web service connector.

maxWaitingTime

String Optional. Maximum time (in milliseconds) to wait for the

reliable messaging sequence to complete before terminating it. If
no value is specied, the service waits indenitely until it receives
a reply.

Output Parameters
fault

Document Conditional. Contents of the fault block.

The fault document references the "pub.soap.utils:soapFault" on
page 806 document type.

transportInfo

Document Conditional. Headers from response and request

messages.
The contents of transportInfo vary depending on the actual
transport used by the service.
Note: The transport information returned by this service is similar to
the transport information returned by a web service connector. For
more information, see Web Services Developers Guide.
The transportInfo parameter contains the following keys:
Key

Description

webMethods Integration Server Built-In Services Reference Version 9.6

836

Odd Header
SOAP Folder

requestHeaders

Document Conditional. Header elds

from the request message issued by the
reliable messaging source.

responseHeaders

Document Conditional. Header elds from

the response.
Each key in responseHeaders represents
a eld (line) of the response header.
Key names represent the names of
header elds. The key values are Strings
containing the values of the elds.
Whether or not the service returns the
responseHeaders parameter depends on
the success or failure of the service. In
the case of failure, the point at which the
failure occurs determines the presence of
the responseHeaders parameter.

status

Document Conditional. Status code from

the request.

statusMessage

Document Conditional. Description of the

status code returned by the underlying
transport.

webMethods Integration Server Built-In Services Reference Version 9.6

837

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

838

Odd Header
Storage Folder

32 Storage Folder
About the Storage Elements ......................................................................................................

840

Locking Considerations ..............................................................................................................

841

Sample Flow Service for Checkpoint Restart ............................................................................

843

Summary of Elements in this Folder .........................................................................................

844

webMethods Integration Server Built-In Services Reference Version 9.6

839

Even Header
Storage Folder

You use the elements in the storage folder to create, close, and delete data stores in the
Integration Server short-term store.

About the Storage Elements

You use the elements in the storage folder to create, close, and delete data stores in the
Integration Server short-term store. Integration Server uses the short-term store for
information that needs to persist across server restarts. For example, if the Integration
Server on which your ow service is executing becomes unavailable and then restarts,
the ow service can check the state information in the short-term store and begin
processing at the point where the ow service was interrupted. The short-term store
exists as the IS_DATASTORE table in an external database identied to Integration
Server through the ISInternal functional alias.
When using the pub.storage services, keep in mind that the short-term store is not
intended to be used as a general-purpose storage engine. Rather, it is primarily provided
to support shared storage of application resources and transient data in an Integration
Server clustered environment. Consequently, Software AG recommends that you do not
use the short-term store to process high volumes, large data records, or to permanently
archive records.
Important: These services are a tool for maintaining state information in the short-term
store. It is up to the developer of the ow service to make sure the ow service keeps
track of its state and correctly handles restarts.
In Release 7.1, the Integration Server 6.1 Repository Server was replaced by a set of
database tables collectively called IS Internal. During Integration Server installation,
you can choose to use the embedded IS Internal database, or you can choose to
use an external RDBMS in which you have created or will create the IS Internal
database component. If you choose the external RDBMS, data associated with the
pub.storage services will be stored in the IS_DATASTORE table in the IS Internal database
component. For DB2, the size of a BLOB column is dened when the table is created;
you might nd that the VALUE column in the IS_DATASTORE table is not wide enough
to accommodate your pub.storage data. If you have not yet created the IS Internal
database component, open the appropriate table creation script below in a text editor
and modify the width of the VALUE column in the IS_DATASTORE table:
Software AG_directory\common\db\scripts\db2\isinternal\version \create\db2_isi
_c_ddl.sql
Software AG_directory\common\db\scripts\db2as400\isinternal\version \create
\db2as400_isi_c_ddl.sql
Where version is the directory that contains the latest version of the external RDBMS.
Tip: The directory with the highest number corresponds to the latest version of the
external RDBMS.

webMethods Integration Server Built-In Services Reference Version 9.6

840

Odd Header
Storage Folder

If you have already created the IS Internal database component and the VALUE column
is not wide enough to accommodate your pub.storage data, use DB2 commands to
modify the width of the VALUE column in the IS_DATASTORE table.

Locking Considerations
The following sections describe in general how the pub.storage services handle locking
requests. See the individual service descriptions for more detailed information.

Entry Locking
To maintain data integrity, the short-term store uses locking to ensure that multiple
threads do not modify the same entry at the same time. For insertions and removals, the
short-term store sets and releases the lock. For updates, the client must set and release
the lock. Using locking improperly, that is, creating a lock but not releasing it, can cause
deadlocks in the short-term store.
The following guidelines can help you avoid short-term store deadlock:
Release locks in the thread through which they were set. In other words, you cannot
set a lock in one thread and release it in another. The safest way to do this is to
release each lock in the ow service that acquired it.
Unlock entries before the ow completes. Entries remain locked until released via
a put (pub.storage:put) or an explicit unlock (pub.storage:unlock). To accomplish this,
always pair a call to pub.storage:get or pub.storage:lock with a call to pub.storage:put or
pub.storage:unlock so that every lock is followed by an unlock. In addition, use a TryCatch paern in your ow service so that an exception does not prevent the ow
service from continuing and releasing the lock.
Set limits on how long the threads will wait for a lock to be set or released. By seing
nite limits, you allow the pub.storage service to release locks after a set amount of
time and thereby avoid a deadlock situation. For more information, see "Wait Time
and Duration" on page 842.
Following these guidelines might not be sucient in some situations. For example,
an Integration Server or hardware crash might result in a prematurely terminated
ow service, thereby leaving an outstanding lock on the pub.storage service. Or, a client
ow service might hang while requesting a lock. In these situations, having limits on
how long a lock can exist (duration) or how long a lock request will wait (wait time) can
prevent an application deadlock while using pub.storage services. For more information
about lock duration and wait time, see "Wait Time and Duration" on page 842.

Data Store Locking

When a pub.storage service locks an entry, the service also implicitly locks the data store
in which the entry resides. This behavior prevents another thread from deleting the

webMethods Integration Server Built-In Services Reference Version 9.6

841

Even Header
Storage Folder

entire data store and the entries it contains while your thread is working with the entry.
When the locked entry is unlocked, the implicit lock on the data store is also released.
Be careful when explicitly unlocking data stores. Consider the following example:
1. User_A locks an item. This creates two locks: an explicit lock on the entry, and an
implicit lock on the data store.
2. User_A later unlocks the data store explicitly while still holding the lock on the
entry.
3. User_B locks, then deletes the data store, including the entry locked by User_A in the
rst step.
When User_A explicitly unlocked the data store in step 2, User_B was able to delete the
entry the User_A was working with.

Automatic Promotion to Exclusive Lock

If a pub.storage service tries to acquire an exclusive lock on an object, but nds a shared
lock from the same thread already in place on the object, the service will try to promote
the lock to an exclusive lock.
If a pub.storage service that requires an exclusive lock encounters a shared or exclusive
lock held by another thread, it will wait until the object becomes available. If the object
remains locked for the period specied by the waitlength parameter passed by the
service, or the value congured on the wa.server.storage.lock.maxWait property, the
service will fail.

Wait Time and Duration

You can control how long Integration Server will wait to obtain a lock and how long it
will hold a lock by using the following server properties:
You can change the lock wait by using the wa.server.storage.lock.maxWait
property from the Settings > Extended Settings screen in Integration Server
Administrator. By default, a lock request will wait 240000 milliseconds (4 minutes)
to obtain a lock. If a pub.storage service species a lock wait through the waitlength
parameter, Integration Server uses this value instead of the value specied on the
wa.server.storage.lock.maxWait property.
You can change the lock duration by using the wa.server.storage.lock.maxDuration
property from the Settings > Extended Settings screen in Integration Server
Administrator. By default, a lock can exist for 180000 milliseconds (3 minutes). After
3 minutes, the server forcibly releases the lock.

webMethods Integration Server Built-In Services Reference Version 9.6

842

Odd Header
Storage Folder

Sample Flow Service for Checkpoint Restart

The following diagram shows how to code checkpoint restart into your services. The
following diagram explains the logic of a ow and shows where the various pub.storage
services are used to achieve checkpoint restart.
Logic to achieve checkpoint restart

webMethods Integration Server Built-In Services Reference Version 9.6

843

Even Header
Storage Folder

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.storage:add

WmPublic. Inserts a new entry into a data store.

pub.storage:closeStore

WmPublic. Obsolete Closes a data store and

unregisters the data store with the server.

pub.storage:deleteStore

WmPublic. Deletes a data store and all its contents.

Any data in the data store is deleted. If the data store
does not exist, the service takes no action.

pub.storage:get

WmPublic. Retrieves a value from a data store and

locks the entry and the data store on behalf of the
thread that invoked the service.

pub.storage:keys

WmPublic. Obtains a list of all the keys in a data store.

pub.storage:listLocks

WmPublic. Lists all pub.storage locks held by the

supplied lock holder or target. If no input is supplied,
the service returns a list of all pub.storage locks.

pub.storage:lock

WmPublic. Locks an entry and/or data store on behalf

of the thread invoking this service.

pub.storage:put

WmPublic. Inserts or updates an entry in a data store.

If the key does not exist in the data store, the entry is
inserted.

pub.storage:registerStore

WmPublic. Obsolete Opens or creates a data store

and registers the store with the server.

pub.storage:releaseLocks

WmPublic. Releases all pub.storage locks held by the

identied lock holders and ids. If both holders and ids
are specied, the service ignores the holders and uses
ids.

pub.storage:remove

WmPublic. Removes an entry from a data store.

webMethods Integration Server Built-In Services Reference Version 9.6

844

Odd Header
Storage Folder

Element

Package and Description

pub.storage:shutdown

WmPublic. Releases internal resources used by the

pub.storage services. This service is run automatically
when the WmPublic package is unloaded and should
not be explicitly invoked by a client.

pub.storage:startup

WmPublic. Performs initialization of internal facilities

used by the pub.storage services. This service is run
automatically when the WmPublic package is loaded
and should not be explicitly invoked by a client.

pub.storage:unlock

WmPublic. Unlocks an entry or a data store.

pub.storage:add
WmPublic. Inserts a new entry into a data store.
If the key already exists in the data store, the pub.storage:add service does nothing.
Input Parameters
storeName

String Name of the data store in which to insert the entry.

key

String Key under which the entry is to be inserted.

value

Document Value (IData object) to be inserted.

Output Parameters
result

String Flag indicating whether the entry was successfully

added. A value of:
true indicates that the new entry was inserted successfully.
false indicates that the entry was not inserted (usually

because an entry for key already exists).

error

String Error message generated while inserting the new entry

into the data store.

webMethods Integration Server Built-In Services Reference Version 9.6

845

Even Header
Storage Folder

pub.storage:closeStore
WmPublic. Obsolete Closes a data store and unregisters the data store with the server.
If the data store is not registered with the server, an exception will be thrown. A data
store cannot be accessed after it has been unregistered. If you want to access the data in
the data store, you need to register the data store again using pub.storage:registerStore.
Input Parameters
storeName

String Name of the data store to close and unregister.

Output Parameters
None.
Usage Notes
This service is obsolete. When the repository was removed for Integration Server version
7.1.2, this service became a NOP (no operation).

pub.storage:deleteStore
WmPublic. Deletes a data store and all its contents. Any data in the data store is deleted.
If the data store does not exist, the service takes no action.
Input Parameters
storeName

String Name of the data store to delete.

waitLength

String Optional. Length of time, in milliseconds, that you want

to wait for this data store to become available for deletion
if it is already locked by another thread. The default is the
default Maximum Lock Wait value, which is specied on the
wa.server.storage.lock.maxWait property. You can update
this property by using the Settings > Extended Settings screen on
the Integration Server Administrator.

Output Parameters
count

String Number of data store entries that were deleted. If the

store does not exist, this value is 0.

webMethods Integration Server Built-In Services Reference Version 9.6

846

Odd Header
Storage Folder

Usage Notes
This service obtains an exclusive lock on the data store, but no locks on the individual
entries in the data store.
If this service nds a shared lock from the same thread on the data store, the service will
automatically promote the lock to an exclusive lock.
The exclusive lock prevents other threads from acquiring locks on the data store or
entries within the data store during the delete operation.

pub.storage:get
WmPublic. Retrieves a value from a data store and locks the entry and the data store on
behalf of the thread that invoked the service.
Important: This service does not automatically release the lock on the data store
or entry after performing the get operation, so you need to make sure the lock is
released by calling the pub.storage:put or pub.storage:unlock service. If you do not release
the lock, other threads will not be able to access the resource until Integration
Server automatically releases the lock after the amount of time specied on the
wa.server.storage.lock.maxDuration property has passed.
Input Parameters
storeName

String Name of the data store from which you want to retrieve
the entry.

key

String Key of the entry whose value you want to retrieve.

waitLength

String Optional. Length of time, in milliseconds, that you

want to wait for this entry to become available if it is
already locked by another thread. The default is the default
Maximum Lock Wait value, which is specied on the
wa.server.storage.lock.maxWait property. You can update
this property by using the Settings > Extended Settings screen on
the Integration Server Administrator.

lockMode

String Optional. Type of lock you want to place on the entry.

Set to:
Exclusive to prevent other threads from reading or

updating the entry while you are using it. The service also
obtains a shared lock on the data store. An exclusive lock on
an entry allows you to modify the entry.

webMethods Integration Server Built-In Services Reference Version 9.6

847

Even Header
Storage Folder

Read is obsolete. If this value is specied, the service obtains

a shared lock.

Share to prevent other threads from obtaining an exclusive

lock on the entry. The service also obtains a shared lock on

the data store. A shared lock on an entry allows you to read,
but not modify, the entry. This is the default.
Output Parameters
value

Document Retrieved entry (IData object). If the requested entry

does not exist, the value of this parameter is null.

Usage Notes
If you request an exclusive lock and the service nds a shared lock from the same thread
on the entry, the service will automatically promote the shared lock on the entry to an
exclusive lock.
When this service locks an entry, it also acquires a shared lock on the associated data
store to prevent another thread from deleting the data store, and the entries it contains,
while your thread has the entry locked.
When storing and retrieving the ow state in the short-term store for checkpoint restart
purposes, be sure the value of key is unique to the transaction.

pub.storage:keys
WmPublic. Obtains a list of all the keys in a data store.
Input Parameters
storeName

String Name of the data store from which you want to obtain a
list of keys.

Output Parameters
keys

String List Keys for the data store specied in storeName .

webMethods Integration Server Built-In Services Reference Version 9.6

848

Odd Header
Storage Folder

pub.storage:listLocks
WmPublic. Lists all pub.storage locks held by the supplied lock holder or target. If no
input is supplied, the service returns a list of all pub.storage locks.
Input Parameters
holder

String Optional. Identies the holder whose

pub.storage locks are to be listed. The format is
"_DataStore_<sessionId :threadId >", where:
sessionId is a unique, internally generated identier for the
client's session in Integration Server.
threadId is a unique, internally generated identier for the
clients thread in Integration Server.

target

String Optional. Identies the target whose pub.storage locks

are to be listed.

Output Parameters
locks

Document List The list of pub.storage locks. This output variable

can be null.
Value

Description

id

String The internal ID of the lock

target

String Item that is locked, specied as a data

store name or the key for an entry

holder

String Holder of the lock. This value is

generated internally by the pub.storage services.

type

String EXCLUSIVE or "SHARE"

count

String Number of lock holders sharing this lock

time

String The time the lock was created.

webMethods Integration Server Built-In Services Reference Version 9.6

849

Even Header
Storage Folder

pub.storage:lock
WmPublic. Locks an entry and/or data store on behalf of the thread invoking this
service.
Important: When you lock an entry or data store using this service, you must release
the lock by using a put (pub.storage:put) or an explicit unlock (pub.storage:unlock). If you
do not release the lock, other threads will not be able to access the resource until
Integration Server automatically releases the lock after the amount of time specied on
the wa.server.storage.lock.maxDuration parameter has passed.
Important: Be careful when releasing locks with the pub.storage:unlock service. If you
release a lock on a data store, another thread can obtain a lock on the data store and
delete it, and the entries it contains, even if your thread still has locks on one or more of
the entries.
Input Parameters
storeName

String Name of the data store containing the entry.

key

String Optional. Key of the entry that you want to lock.

If key is not supplied and you request:
A shared lock, the service obtains a shared lock on the data
store, allowing other threads to read and modify entries, but
not to delete them.
An exclusive lock, the service obtains an exclusive lock on the
data store, preventing other threads from locking the data
store and the entries, thereby preventing those threads from
reading, modifying, or deleting the entries or the data store.
If both storeName and key are specied and you request:
A shared lock, the service obtains a shared lock on the data
store and the entry.
An exclusive lock, the service obtains a shared lock on the
data store and an exclusive lock on the entry.

waitLength

String Optional. Length of time, in milliseconds, that you

want to wait for this entry to become available if it is
already locked by another thread. The default is the default
Maximum Lock Wait value, which is specied on the
wa.server.storage.lock.maxWait property. You can update

webMethods Integration Server Built-In Services Reference Version 9.6

850

Odd Header
Storage Folder

this property by using the Settings > Extended Settings screen on

the Integration Server Administrator.
lockMode

String Optional. Type of lock you want to place on the entry or

data store. Set to:
Exclusive to prevent other threads from obtaining a lock on

the data store or entry.

An exclusive lock on an entry allows you to modify the entry,

and prevents other threads from reading or modifying the
entry.
An exclusive lock on a data store also locks the entries in
the data store. In addition, an exclusive lock on a data store
allows you to delete the data store.
Read is obsolete. If this value is specied, the service obtains

a shared lock.

Share to prevent other threads from obtaining an exclusive

lock on an entry or a data store. A shared lock on an entry

allows you to read, but not modify, the entry. A shared lock
on a data store prevents another thread from deleting the
data store. This is the default.
Output Parameters
None.
Usage Notes
If you have not specied a key , and your ow service does not invoke pub.storage:put or
pub.storage:unlock, or your service throws an exception before invoking pub.storage:put or
pub.storage:unlock, the entire data store remains locked until the amount of time specied
on the wa.server.storage.lock.maxDuration parameter has passed.
If the key does not exist in the data store at the time your ow service
executes, the pub.storage:lock service is a NOP (no operation). Set the
wa.server.storage.addKeyToStoreIfNotPresent parameter to true if you want the
pub.storage:lock service to add the specied key to the data store if the key does not exist at
the time the service executes. When the wa.server.storage.addKeyToStoreIfNotPresent
parameter is set to true, the pub.storage:lock service creates the specied key, assigns it a
NULL value, and then locks the entry in the data store.
If you request an exclusive lock on an entry, the service obtains an exclusive lock on
the entry and a shared lock on the data store. If this service nds a shared lock from the
same thread on the entry, the service will automatically promote the shared lock on the
entry to an exclusive lock.
If you request a shared lock on an entry, the service obtains a shared lock on the entry
and a shared lock on the data store.

webMethods Integration Server Built-In Services Reference Version 9.6

851

Even Header
Storage Folder

If you request a shared lock on an entry or a data store and this service nds an
exclusive lock from the same thread, the existing exclusive lock will be reused. The
exclusive lock will not be demoted to a shared lock.
If you request an exclusive lock on a data store, and this service nds a shared lock from
the same thread on the data store, the service will automatically promote the shared lock
on the data store to an exclusive lock.

pub.storage:put
WmPublic. Inserts or updates an entry in a data store. If the key does not exist in the
data store, the entry is inserted.
If the requested entry is not currently locked by the thread that invoked this service, the
pub.storage:put service will automatically aempt to lock the entry for the duration of the
put operation.
The service obtains an exclusive lock on the entry and a shared lock on the data store.
If the service nds a shared lock from the same thread on the entry, the service will
automatically promote the shared lock to an exclusive lock.
This service releases the lock when the put operation has completed.
Input Parameters
storeName

String Name of the data store into which you want to insert or
update the entry.

value

Document Value (IData object) to be inserted or updated.

waitLength

String Optional. Length of time, in milliseconds, that you want

to wait for this entry to become available if it is already locked
by another thread. If the wait length expires before a lock
is obtained, the service fails and throws an exception. The
default is the default Maximum Lock Wait value, which is
specied on the wa.server.storage.lock.maxWait property.
You can update this property by using the Settings > Extended
Settings screen on the Integration Server Administrator.
This parameter is used only when your service did not
explicitly lock the entry beforehand.

key

String Key where you want to insert or update the entry.

webMethods Integration Server Built-In Services Reference Version 9.6

852

Odd Header
Storage Folder

Output Parameters
error

String Error message generated while inserting the new entry

into the data store.

Usage Notes
When storing and retrieving the ow state in the short-term store for checkpoint restart
purposes, be sure the value of key is unique to the transaction.

pub.storage:registerStore
WmPublic. Obsolete Opens or creates a data store and registers the store with the
server.
A data store must be registered before it can be accessed. If the store is already
registered with the server, this service does nothing.
Input Parameters
storeName

String Name of the data store to register.

Output Parameters
None.

pub.storage:releaseLocks
WmPublic. Releases all pub.storage locks held by the identied lock holders and ids. If
both holders and ids are specied, the service ignores the holders and uses IDs.
This service is intended primarily for administrators. It is most useful when used in
combination with pub.storage:listLocks. You can map the locks/holder string list from
that service to the holders input variable in this service or the locks/id string list to the
ids input variables. If neither ids nor holders are supplied, no locks are released.
Important: Use this service with care. It will release locks held by active threads and could
cause their processing to fail. In addition, if you release a lock on a data store, another
thread can obtain a lock on the data store and delete it, and the entries it contains, even
if the original thread still has locks on one or more of the entries.

webMethods Integration Server Built-In Services Reference Version 9.6

853

Even Header
Storage Folder

Input Parameters
holders

String List Optional. Holders whose pub.storage locks are to be

released.

ids

String Optional. Ids whose pub.storage locks are to be released.

Output Parameters
count

String List Number of locks that were released.

pub.storage:remove
WmPublic. Removes an entry from a data store. This service obtains an exclusive lock on
the entry and a shared lock on the data store.
Input Parameters
storeName

String Name of the data store from which to remove an entry.

key

String Key of the entry that you want to remove.

waitLength

String Optional. Length of time, in milliseconds, that you

want to wait for this entry to become available for deletion
if it is already locked by another thread. The default is the
default Maximum Lock Wait value, which is specied on the
wa.server.storage.lock.maxWait property. You can update
this property by using the Settings > Extended Settings screen on
the Integration Server Administrator.

Output Parameters
result

String Flag indicating whether the entry was successfully

removed. A value of:
true indicates that the entry was removed successfully.
false indicates that the entry was not removed (usually

because an entry for key does not exist).

webMethods Integration Server Built-In Services Reference Version 9.6

854

Odd Header
Storage Folder

pub.storage:shutdown
WmPublic. Releases internal resources used by the pub.storage services. This service is
run automatically when the WmPublic package is unloaded and should not be explicitly
invoked by a client.

pub.storage:startup
WmPublic. Performs initialization of internal facilities used by the pub.storage services.
This service is run automatically when the WmPublic package is loaded and should not
be explicitly invoked by a client.

pub.storage:unlock
WmPublic. Unlocks an entry or a data store.
When a ow service retrieves an entry using the pub.storage:get service, the entry is locked
to prevent modication by other users before the ow completes. The entry remains
locked until the lock owner invokes a pub.storage:put service. To unlock a service without
using the pub.storage:put service, use the pub.storage:unlock service.
In addition, if a ow service uses the pub.storage:lock service to lock an entry or data store,
you must use the pub.storage:unlock or pub.storage:put service to release the lock.
Important: Be careful when releasing locks with this service. If you release a lock on
a data store, another thread can obtain a lock on the data store and delete it, and the
entries it contains, even if the original thread still has locks on one or more of the entries.
Input Parameters
storeName

String Name of the data store in which to unlock an entry.

key

String Optional. Key of the entry that you want to unlock. If

key is not supplied, the lock will be removed from the data
store specied in storeName , but any locks on entries in the
data store will remain.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

855

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

856

Odd Header
String Folder

33 String Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

858

857

Even Header
String Folder

You use the elements in the string folder to perform string manipulation and
substitution operations.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.string:base64Decode

WmPublic. Decodes a Base-64 encoded string into

a sequence of bytes.

pub.string:base64Encode

WmPublic. Converts a sequence of bytes into a

Base64-encoded String.

pub.string:bytesToString

WmPublic. Converts a sequence of bytes to a

String.

pub.string:concat

WmPublic. Concatenates two strings.

pub.string:HTMLDecode

WmPublic. Replaces HTML character entities with

native characters.

pub.string:HTMLEncode

WmPublic. Replaces HTML-sensitive characters

with equivalent HTML character entities.

pub.string:indexOf

WmPublic. Returns the index of the rst

occurrence of a sequence of characters in a string.

pub.string:length

WmPublic. Returns the length of a string.

pub.string:lookupDictionary

WmPublic. Looks up a given key in a hash

table and returns the string to which that key is
mapped.

pub.string:lookupTable

WmPublic. Locates a key in a String Table and

returns the string to which that key is mapped.

pub.string:makeString

WmPublic. Builds a single string by concatenating

the elements of a String List.

webMethods Integration Server Built-In Services Reference Version 9.6

858

Odd Header
String Folder

Element

Package and Description

pub.string:messageFormat

WmPublic. Formats an array of strings into a

given message paern.

pub.string:numericFormat

WmPublic. Formats a number into a given

numeric paern.

pub.string:objectToString

WmPublic. Converts an object to string

representation using the Java toString() method of
the object.

pub.string:padLeft

WmPublic. Pads a string to a specied length by

adding pad characters to the beginning of the
string.

pub.string:padRight

WmPublic. Pads a string to a specied length by

adding pad characters to the end of the string.

pub.string:replace

WmPublic. Replaces all occurrences of a specied

substring with a substitute string.

pub.string:stringToBytes

WmPublic. Converts a string to a byte array.

pub.string:substring

WmPublic. Returns a substring of a given string.

pub.string:tokenize

WmPublic. Tokenizes a string using specied

delimiter characters and generates a String List
from the resulting tokens.

pub.string:toLower

WmPublic. Converts all characters in a given

string to lowercase.

pub.string:toUpper

WmPublic. Converts all characters in a given

string to uppercase.

pub.string:trim

WmPublic. Trims leading and trailing white space

from a given string.

pub.string:URLDecode

WmPublic. Decodes a URL-encoded string.

pub.string:URLEncode

WmPublic. URL-encodes a string.

webMethods Integration Server Built-In Services Reference Version 9.6

859

Even Header
String Folder

pub.string:base64Decode
WmPublic. Decodes a Base-64 encoded string into a sequence of bytes.
Input Parameters
string

String A Base64-encoded String to decode into bytes.

Output Parameters
value

byte[ ] The sequence of bytes decoded from the Base64-encoded

String.

encoding

String Optional. Species the encoding method. Default value

is ASCII.

pub.string:base64Encode
WmPublic. Converts a sequence of bytes into a Base64-encoded String.
Input Parameters
bytes

byte[ ] Sequence of bytes to encode into a Base64-encoded

String.

useNewLine

String Optional. Flag indicating whether to retain or remove

the line breaks. Set to:
true to retain the line breaks. This is the default.
false to remove the line breaks.

encoding

String Optional. Species the encoding method. Default value

is ASCII.

Output Parameters
value

String Base64-encoded String encoded from the sequence of

bytes.

webMethods Integration Server Built-In Services Reference Version 9.6

860

Odd Header
String Folder

Usage Notes
By default, the pub.string:base64Encode service inserts line breaks after 76 characters of
data, which is not the canonical lexical form expected by implementations such as
MTOM. You can use the useNewLine parameter to remove the line breaks. For more
information about MTOM implementations, refer to Web Services Developers Guide.

pub.string:bytesToString
WmPublic. Converts a sequence of bytes to a String.
Input Parameters
bytes

byte[ ] Sequence of bytes to convert to a String.

encoding

String Optional. Name of a registered, IANA character set

(for example, ISO-8859-1). If you specify an unsupported
encoding, the system throws an exception.
To use the default encoding, set encoding to autoDetect.

Output Parameters
string

String String representation of the contents of bytes .

pub.string:concat
WmPublic. Concatenates two strings.
Input Parameters
inString1

String String to which you want to concatenate another string.

inString2

String String to concatenate to inString1 .

Output Parameters
value

String Result of concatenating inString1 with inString2

(inString1 + inString2 ).

webMethods Integration Server Built-In Services Reference Version 9.6

861

Even Header
String Folder

pub.string:HTMLDecode
WmPublic. Replaces HTML character entities with native characters.
Specically, the service:
Replaces this HTML
character entity...

With...

&gt;

>

&lt;

<

&amp;

&

&quot;

"

Input Parameters
inString

String An HTML-encoded String.

Output Parameters
value

String Result from decoding the contents of inString . Any

HTML character entities that existed in inString will appear as
native characters in value .

pub.string:HTMLEncode
WmPublic. Replaces HTML-sensitive characters with equivalent HTML character
entities.
Specically, this service:
Replaces this native
language character...

With...

>

&gt;

<

&lt;

webMethods Integration Server Built-In Services Reference Version 9.6

862

Odd Header
String Folder

Replaces this native

language character...

With...

&

&amp;

"

&quot;

&
39

These translations are useful when displaying text in an HTML context.

Input Parameters
inString

String The character you want to encode in HTML.

Output Parameters
value

String Result from encoding the contents of inString . Any

HTML-sensitive characters that existed in inString (for
example, > or &) will appear as the equivalent HTML
character entities in value .

pub.string:indexOf
WmPublic. Returns the index of the rst occurrence of a sequence of characters in a
string.
Input Parameters
inString

String String in which you want to locate a sequence of

characters.

subString

String Sequence of characters to locate.

fromIndex

String Optional. Index of inString from which to start the

search. If no value is specied, this parameter contains 0 to
indicate the beginning of the string.

webMethods Integration Server Built-In Services Reference Version 9.6

863

Even Header
String Folder

Output Parameters
value

String Index of the rst occurrence of subString in inString . If

no occurrence is found, this parameter contains -1.

pub.string:length
WmPublic. Returns the length of a string.
Input Parameters
inString

String String whose length you want to discover.

Output Parameters
value

String The number of characters in inString .

pub.string:lookupDictionary
WmPublic. Looks up a given key in a hash table and returns the string to which that key
is mapped.
Input Parameters
hashtable

java.util.Hashtable Hash table that uses String objects for keys

and values.

key

String Key in hashtable whose value you want to retrieve.

Note: The key is case sensitive.

Output Parameters
value

String Value of the string to which key is mapped. If the

requested key in hashtable is null or if key is not mapped to
any value in hashtable , the service returns null.

webMethods Integration Server Built-In Services Reference Version 9.6

864

Odd Header
String Folder

pub.string:lookupTable
WmPublic. Locates a key in a String Table and returns the string to which that key is
mapped.
Input Parameters
lookupTable

String [ ] [ ] A multi-row, multi-column string table in which to

search.

keyColumnIndex

String Index of the "key" column. Default is 0.

valueColumnIndex

String Index of the "value" column. Default is 1.

key

String Key to locate.

Note: The key is case sensitive.

ignoreCase

String Optional. Flag indicating whether to perform a casesensitive or case-insensitive search. Set to:
true to perform a case-insensitive search.
false to perform a case-sensitive search. This is the default.

useRegex

String Optional. Flag indicating whether the values in the table

are to be interpreted as regular expressions.
Note: The regular expressions in the table should not include
slashes. For example, use hello.*, not /hello.*/.
Set to:
true to interpret the key column values in the table as

regular expressions.

false to interpret the key column values in the table as

literal values (that is, not regular expressions). This is the

default.
Output Parameters
value

String First value in the "value" column whose key matches

key . If no match is found, this parameter is null.

webMethods Integration Server Built-In Services Reference Version 9.6

865

Even Header
String Folder

pub.string:makeString
WmPublic. Builds a single string by concatenating the elements of a String List.
Input Parameters
elementList

String List Strings to concatenate.

separator

String String to insert between each non-null element in

elementList .

Output Parameters
value

String Result from concatenating the strings in elementList .

Strings are separated by the characters specied in separator .

pub.string:messageFormat
WmPublic. Formats an array of strings into a given message paern.
Input Parameters
paern

String Message that includes "placeholders" where elements

from argumentList are to be inserted. The message can contain
any sequence of characters. Use the {n} placeholder to insert
elements from argumentList , where n is the index of the
element that you want to insert. For example, the following
paern string inserts elements 0 and 1 into the message:
Test results: {0} items passed, {1} items failed.

Note: Do not use any characters except digits for n .

argumentList

String List Optional. List of strings to use to populate paern .

If argumentList is not supplied, the service will not replace
placeholders in paern with actual values.

webMethods Integration Server Built-In Services Reference Version 9.6

866

Odd Header
String Folder

Output Parameters
value

String Result from substituting argumentList into paern . If

paern is empty or null, this parameter is null.

pub.string:numericFormat
WmPublic. Formats a number into a given numeric paern.
Input Parameters
num

String The number to format.

paern

String A paern string that describes the way in which num is

to be formaed:
This symbol...

Indicates...

A digit.

A digit. Leading zeroes will not be

shown.

A placeholder for a decimal separator.

A placeholder for a grouping separator.

A separation in format.

The default negative prex.

That num will be multiplied by 100 and

shown as a percentage.

Any character used as a prex or sux

(for example, A, $).

'

That special characters are to be used as

literals in a prex or sux. Enclose the
special characters within '' (for example,
'#').

webMethods Integration Server Built-In Services Reference Version 9.6

867

Even Header
String Folder

The following are examples of paern strings:

Pattern

Description

,

Use commas to separate into groups of

three digits. The pound sign denotes a
digit and the comma is a placeholder for
the grouping separator.

,

Use commas to separate into groups of

four digits.

$
.00

Show digits before the decimal point

as needed and exactly two digits after
the decimal point. Prex with the $
character.

'
'
.0

Show digits before the decimal point

as needed and exactly one digit after
the decimal point. Prex with the #
character. The rst character in a paern
is the dollar sign ($). The pound sign
denotes a digit and the period is a
placeholder for decimal separator.

Output Parameters
value

Stringnum formaed according to paern . If paern is

an empty (not null) string, the default paern of comma
separators is used and the number of digits after the decimal
point remains unchanged.

pub.string:objectToString
WmPublic. Converts an object to string representation using the Java toString() method
of the object.
Input Parameters
object

Object The object to be converted to string representation.

webMethods Integration Server Built-In Services Reference Version 9.6

868

Odd Header
String Folder

Output Parameters
string

String String representation of the input object converted using

the Java toString() method of the object.

pub.string:padLeft
WmPublic. Pads a string to a specied length by adding pad characters to the beginning
of the string.
Input Parameters
inString

String String that you want to pad.

padString

String Characters to use to pad inString .

length

String Total length of the resulting string, including pad

characters.

Output Parameters
value

String Contents of inString preceded by as many pad

characters as needed so that the total length of the string
equals length .

Usage Notes
If padString is longer than one character and does not t exactly into the resulting string,
the beginning of padString is aligned with the beginning of the resulting string. For
example, suppose inString equals shipped and padString equals x9y.
If length equals...

Then value will contain...

shipped

10

x9yshipped

12

x9x9yshipped

webMethods Integration Server Built-In Services Reference Version 9.6

869

Even Header
String Folder

If inString is longer than length characters, only the last length characters from inString
are returned. For example, if inString equals acct1234 and length equals 4, value will
contain 1234.

pub.string:padRight
WmPublic. Pads a string to a specied length by adding pad characters to the end of the
string.
Input Parameters
inString

String String that you want to pad.

padString

String Characters to use to pad inString .

length

String Total length of the resulting string, including pad

characters.

Output Parameters
value

String Contents of inString followed by as many pad characters

as needed so that the total length of the string equals length .

Usage Notes
If padString is longer than one character and does not t exactly into the resulting string,
the end of padString is aligned with the end of the resulting string. For example, suppose
inString equals shipped and padString equals x9y.
If length equals...

Then value will contain...

shipped

10

shippedx9y

12

shippedx9y9y

If inString is longer than length characters, only the rst length characters from inString
are returned. For example, if inString equals 1234acct and length equals 4, value will
contain 1234.

webMethods Integration Server Built-In Services Reference Version 9.6

870

Odd Header
String Folder

pub.string:replace
WmPublic. Replaces all occurrences of a specied substring with a substitute string.
Input Parameters
inString

String String containing the substring to replace.

searchString

String Substring to replace within inString .

replaceString

String Character sequence that will replace searchString .

If this parameter is null or empty, the service removes all
occurrences of searchString from inString .

useRegex

String Optional. Flag indicating whether searchString is a

regular expression. When regular expressions are used
to specify a search string, replaceString may also contain
interpolation variables (for example, "$1") that match
parenthetical subexpressions in searchString .
Set to:
true to indicate that searchString is a regular expression.
false to indicate that searchString is not a regular

expression. This is the default.

Output Parameters
value

String Contents of inString with replacements made.

pub.string:stringToBytes
WmPublic. Converts a string to a byte array.
Input Parameters
string

String String to convert to a byte[ ].

encoding

String Optional. Name of a registered, IANA character set that

species the encoding to use when converting the String to an
array of bytes (for example: ISO-8859-1).

webMethods Integration Server Built-In Services Reference Version 9.6

871

Even Header
String Folder

To use the default encoding, set this value to autoDetect. If

you specify an unsupported encoding, an exception will be
thrown.
Output Parameters
bytes

byte[ ] Contents of string represented as a byte[ ].

pub.string:substring
WmPublic. Returns a substring of a given string.
Input Parameters
inString

String String from which to extract a substring.

beginIndex

String Beginning index of the substring to extract (inclusive).

endIndex

String Ending index of the substring to extract (exclusive). If

this parameter is null or empty, the substring will extend to
the end of inString .

Output Parameters
value

String Substring from beginIndex and extending to the

character at endIndex - 1.

pub.string:tokenize
WmPublic. Tokenizes a string using specied delimiter characters and generates a String
List from the resulting tokens.
This service does not return delimiters as tokens.
Input Parameters
inString

String String you want to tokenize (that is, break into delimited
chunks).

webMethods Integration Server Built-In Services Reference Version 9.6

872

Odd Header
String Folder

delim

String Delimiter characters. If null or empty, the service uses

the default delimiters \t\n\r, where t, n, and r represent the
white space characters tab, new line, and carriage return).

Output Parameters
valueList

String List Strings containing the tokens extracted from

inString .

pub.string:toLower
WmPublic. Converts all characters in a given string to lowercase.
Input Parameters
inString

String String to convert.

language

String Optional. Lowercase, two-leer ISO-639 code. If this

parameter is null, the system default is used.

country

String Optional. Uppercase, two-leer ISO-3166 code. If this

parameter is null, the system default is used.

variant

String Optional. Vendor and browser-specic code. If null, this

parameter is ignored.

Output Parameters
value

String Contents of inString , with all uppercase characters

converted to lowercase.

pub.string:toUpper
WmPublic. Converts all characters in a given string to uppercase.
Input Parameters
inString

String String to convert.

webMethods Integration Server Built-In Services Reference Version 9.6

873

Even Header
String Folder

language

String Optional. Lowercase, two-leer ISO-639 code. If this

parameter is null, the system default is used.

country

String Optional. Uppercase, two-leer ISO-3166 code. If this

parameter is null, the system default is used.

variant

String Optional. Vendor and browser-specic code. If null, this

parameter is ignored.

Output Parameters
value

String Contents of inString , with all lowercase characters

converted to uppercase.

pub.string:trim
WmPublic. Trims leading and trailing white space from a given string.
Input Parameters
inString

String String to trim.

Output Parameters
value

String Contents of inString with white space trimmed from

both ends.

pub.string:URLDecode
WmPublic. Decodes a URL-encoded string.
Input Parameters
inString

String URL-encoded string to decode.

Output Parameters
value

String Result from decoding inString . If inString contained

plus (+) signs, they will appear in value as spaces. If inString

webMethods Integration Server Built-In Services Reference Version 9.6

874

Odd Header
String Folder

contained %hex encoded characters, they will appear in value

as the appropriate native character.

pub.string:URLEncode
WmPublic. URL-encodes a string.
Encodes characters the same way that data posted from a WWW form is encoded (that
is, the application/x-www-form-urlencoded MIME type).
Input Parameters
inString

String String to URL-encode.

Output Parameters
value

String Result from URL-encoding inString . If inString

contained non-alphanumeric characters (except [-_.*@]),
they will appear in value as their URL-encoded equivalents
(% followed by a two-digit hex code). If inString contained
spaces, they will appear in value as plus (+) signs.

webMethods Integration Server Built-In Services Reference Version 9.6

875

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

876

Odd Header
Sync Folder

34 Sync Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

878

877

Even Header
Sync Folder

You use the elements in the sync folder to coordinate the execution of services. You can
coordinate services so that a waiting service will execute if and only if a notifying service
produces the input required by the waiting service within a specied time period. The
synchronization services wait for and send notication using a key. A notifying service
only delivers input to waiting services with the same key.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.sync:notify

WmPublic. Noties services waiting on the specied key and

delivers the input document to the services.

pub.sync:shutdown

WmPublic. Releases internal resources used by the pub.sync

services. This service is run automatically when the
WmPublic package is unloaded and should not be explicitly
invoked by a client.

pub.sync:wait

WmPublic. Allows one or more services to wait for delivery

of data from a notifying service.

pub.sync:notify
WmPublic. Noties services waiting on the specied key and delivers the input
document to the services.
Input Parameters
key

String Name of the key. Waiting services with the same key will
receive notication and input from this service.

value

Document Input for the waiting services.

Output Parameters
notied

String Number of waiting services that received the

notication. The notied count only includes services waiting
at the time the pub.sync:notify service was called. Wait requests

webMethods Integration Server Built-In Services Reference Version 9.6

878

Odd Header
Sync Folder

that start after pub.sync:notify executes are not included in the

notied count.
Usage Notes
The value of the server property wa.server.sync.timeout determines the maximum
length of time that the notication can exist. However, if a service with an exclusive wait
is registered for the notication key , the notication ends as soon as the exclusive wait
receives the notication.

pub.sync:shutdown
WmPublic. Releases internal resources used by the pub.sync services. This service is
run automatically when the WmPublic package is unloaded and should not be explicitly
invoked by a client.

pub.sync:wait
WmPublic. Allows one or more services to wait for delivery of data from a notifying
service.
Input Parameters
key

String Name of the key for which the service is waiting

notication. The service receives notication and data from a
notifying service with the same key .

time

String Length of time, in seconds, the service waits for

notication. If the request times out, an exception is thrown.
Note: A time value of -1 or 0 results in undened behavior.

exclusive

String Optional. Flag indicating whether this service waits

exclusively for the notication and prevents other services
from waiting for a notication for the specied key . Set to:
yes to specify that this service waits exclusively for the

notication from the specied key . Integration Server

prevents other services from waiting for the specied
notication.

no to allow multiple services to wait for notication. This is

the default.

webMethods Integration Server Built-In Services Reference Version 9.6

879

Even Header
Sync Folder

Output Parameters
value

Document Input delivered by the notifying service.

Usage Notes
Any service that is waiting for the key notication, receives the notication as long as the
lifespan of the wait request overlaps with the lifespan of the notication. However, if a
service with an exclusive wait registers for the notication key , the notication ends as
soon as the exclusive wait is notied.
An exclusive wait might not be the only wait that receives the notication. For example,
an exclusive wait might be registered after other non-exclusive waits have been notied.
However, once an exclusive wait is registered, it will be the last wait to be notied.
Notication must occur within the time period specied by the time parameter. If
the wait request expires before receiving a notication, Integration Server throws a
ServiceException: [ISS.0086.9067] wait timed out.
If the pub.sync.wait service species a key for which an exclusive wait already exits,
Integration Server returns a ServiceException: [ISS.0086.9065] already in exclusive wait.
If the pub.sync.wait service species an exclusive wait for a key for which regular wait
threads already exits, Integration Server throws a ServiceException: [ISS.0086.9066]
cannot obtain exclusive wait.

webMethods Integration Server Built-In Services Reference Version 9.6

880

Odd Header
Synchronization Folder

35 Synchronization Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

882

881

Even Header
Synchronization Folder

You use the elements in the synchronization folder to perform latching and crossreferencing operations in a publish-and-subscribe integration.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.synchronization.latch:closeLatch

WmPublic. Closes the latch for a resource.

pub.synchronization.latch:isLatchClosed

WmPublic. Checks a resource's latch

status.

pub.synchronization.latch:openLatch

WmPublic. Opens the latch for a resource.

pub.synchronization.xref:createXReference

WmPublic. Creates a cross-reference

between a canonical key and a native ID.

pub.synchronization.xref:deleteByObjectId

WmPublic. Removes all cross-reference

records associated with a particular
process or synchronization.

pub.synchronization.xref:deleteXReference

WmPublic. Deletes a cross-reference

record from the cross-reference table.

pub.synchronization.xref:getCanonicalKey

WmPublic. Retrieves the canonical key

for a specied native ID.

pub.synchronization.xref:getNativeId

WmPublic. Retrieves the native ID of

a resource record associated with a
canonical key.

pub.synchronization.xref:insertXReference

WmPublic. Inserts a cross-reference

between a native ID and a canonical key.

pub.synchronization.latch:closeLatch
WmPublic. Closes the latch for a resource.
The resource cannot be acted upon while the latch is closed. By closing a latch, you can
prevent a circular update between the source and target resources.

webMethods Integration Server Built-In Services Reference Version 9.6

882

Odd Header
Synchronization Folder

Input Parameters
appId

String A unique identier for the target resource for which you want
to close a latch. Typically, the appId is the name of the adapter or the
resource.

canonicalKey

String The canonical key. A unique identier for the canonical

document used in the synchronization.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization,
such as "order" or "customer."

Output Parameters
None.

pub.synchronization.latch:isLatchClosed
WmPublic. Checks a resource's latch status.
By checking the latch status, you can determine whether a resource has been updated.
Input Parameters
appId

String A unique identier for the resource for which you want to
check the latch status. Typically, the appId is the name of the adapter
or the resource.

canonicalKey

String The canonical key. A unique identier for the canonical

document used in the synchronization.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization,
such as "order" or "customer."

Output Parameters
isLatchClosed

String The status of the latch. A value of:

webMethods Integration Server Built-In Services Reference Version 9.6

883

Even Header
Synchronization Folder

true indicates that the latch is closed. The resource has been

updated.

false indicates that the latch is open. The resource has not been

updated.
Usage Notes

Use the latch status to determine whether or not to update the resource.
If the latch is closed (isLatchClosed is true), the resource is already updated. Use the
pub.synchronization.latch:openLatch service to end execution of the update and open the
latch in preparation for the next update to the resource.
If the latch is open (isLatchClosed is false), the resource has not yet been updated.
Invoke services to locate and update the record in the target resource. Then invoke
the pub.synchronization.latch:closeLatch service to close the latch and prevent circular
updates.
For more information about using the pub.synchronization.latch services to prevent echo
suppression, see the Publish-Subscribe Developers Guide.
See Also
pub.synchronization.latch:closeLatch
pub.synchronization.latch:openLatch

pub.synchronization.latch:openLatch
WmPublic. Opens the latch for a resource.
By opening the latch, you can end propagation of the update and make the resource
available for future updates.
Input Parameters
appId

String A unique identier for the resources for which you want to
open the latch. Typically, the appId is the name of the adapter or the
resource.

canonicalKey

String The canonical key. A unique identier for the canonical

document used in the synchronization.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization, such
as "order" or "customer."

webMethods Integration Server Built-In Services Reference Version 9.6

884

Odd Header
Synchronization Folder

Output Parameters
None.

pub.synchronization.xref:createXReference
WmPublic. Creates a cross-reference between a canonical key and a native ID.
Input Parameters
appId

String A unique identier for the resource (application) for which you
want to create a cross-reference to a canonical key.

nativeId

String A unique identier for the resource record for which you want
to create a cross-reference to a canonical key.

canonicalKey

String Optional. A canonical key. If a canonical key is not provided

as input, createXReference creates the canonical key and the crossreference.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization, such
as "order" or "customer."

Output Parameters
canonicalKey

String The canonical key. This key correlates native IDs of records
from dierent resources. This will be a new, unique key if
canonicalKey was not provided as an input parameter. If canonicalKey
was provided as input, this output parameter returns the same value.

Usage Notes
The canonical document is the standard format that a document assumes while it
travels through webMethods components. A source resource will convert or map
data from its proprietary data format into the canonical format before publishing the
document. A target resource (a subscriber to the canonical document) will map the
canonical document to the target resource's proprietary data format before processing
the document. The canonical document acts as the intermediary data format between
resources.
On the source side of the synchronization, use the createXReference service to create the
canonical key for the canonical document and establish a cross-reference between the

webMethods Integration Server Built-In Services Reference Version 9.6

885

Even Header
Synchronization Folder

record in the source application and the canonical document. Before publishing the
canonical document, link the generated canonicalKey to the canonical document.
On the target side of synchronization, use the pub.synchronization.xref:insertXReference service
to insert the cross-reference between a canonical key and the native ID for the record in
the target resource.
For more information about using the createXReference service to create synchronizations,
see the Publish-Subscribe Developers Guide
See Also
pub.synchronization.xref:insertXReference

pub.synchronization.xref:deleteByObjectId
WmPublic. Removes all cross-reference records associated with a particular process or
synchronization.
Input Parameters
objectId

String A unique identier for the object or process for which you want
to delete all cross-reference records. Typically, the objectId eld is set
to the name of the business process for which you are performing
synchronization, such as "order" or "customer."

Output Parameters
None.
Usage Notes
You can use this service to purge unwanted cross-reference records from the crossreference table. For example, if you wanted to delete all cross-reference records for the
purchaseOrder synchronization, specify "purchaseOrder" as the objectId .

pub.synchronization.xref:deleteXReference
WmPublic. Deletes a cross-reference record from the cross-reference table.
This service deletes only one cross-reference record.
Input Parameters
appId

String A unique identier for the resource (application) for which you
want to delete a cross-reference record.

webMethods Integration Server Built-In Services Reference Version 9.6

886

Odd Header
Synchronization Folder

canonicalKey

String The canonical key. A unique identier for the canonical

document for which you want to delete a cross-reference.

objectId

String A unique identier for the object or process for which you
want to delete a cross-reference. Typically, the objectId eld is set
to the name of the business process for which you are performing
synchronization, such as "order" or "customer."

Output Parameters
None.

pub.synchronization.xref:getCanonicalKey
WmPublic. Retrieves the canonical key for a specied native ID.
Input Parameters
appId

String A unique identier for the resource (application) that contains

the native ID for which you want to retrieve a canonical key.

nativeId

String A unique identier for the resource record for which you want
to obtain the canonical key.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization, such
as "order" or "customer."

Output Parameters
canonicalKey

String The canonical key for the provided native ID. If the requested
key cannot be found or does not exist in the cross-reference table, an
empty string is returned.

Usage Notes
You can use this service to determine whether you need to insert or update a record in
the resource.
If the canonical key exists (canonicalKey contains a value), a cross-reference
between the native ID and the canonical key already exists. The record
with the specied nativeId is not a new record. You can then invoke the

webMethods Integration Server Built-In Services Reference Version 9.6

887

Even Header
Synchronization Folder

pub.synchronization.latch:isLatchClosed service to determine whether the resource needs to

be updated.
If the canonical key does not exist (canonicalKey contains an empty
string), then the record with the native ID is a new record. You can use the
pub.synchronization.xref:createXReference service to generate the canonical key and create
the cross-reference to the native ID.
For more information about using the getCanonicalKey service in synchronizations, see the
Publish-Subscribe Developers Guide.
See Also
pub.synchronization.latch:isLatchClosed
pub.synchronization.xref:createXReference

pub.synchronization.xref:getNativeId
WmPublic. Retrieves the native ID of a resource record associated with a canonical key.
Input Parameters
appId

String A unique identier for the resource from which you want to
retrieve the native ID associated with the provided canonical key.

canonicalKey

String The canonical key for which you want to obtain the
corresponding native ID.

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization, such
as "order" or "customer."

Output Parameters
nativeId

String A unique identier for the resource record associated with the
provided canonical key. If the requested nativeId cannot be found in
the cross-reference table, an empty string is returned.

Usage Notes
You can use the getNativeId service on the target side of a synchronization to determine if
the record in the target resource needs to be inserted or just updated.
If the native ID does not exist (the nativeId eld contains an empty string) and you
specied the correct input values, then the record does not exist in the resource. You
will need to insert the record in the resource to generate the native ID. Then use the
webMethods Integration Server Built-In Services Reference Version 9.6

888

Odd Header
Synchronization Folder

pub.synchronization.xref:insertXReference service to insert a cross-reference between the

native ID and the canonical key.
If the native ID exists (the nativeId eld contains a value), then a cross-reference
between the canonical key and the record already exists. The record already exists in
the resource and only needs to be updated.
After you insert or update the record in the resource, make sure to use
pub.synchronization.latch:closeLatch to close the latch for the record to prevent circular
updates (echoes).
For more information about using the getNativeId service in synchronizations, see the
Publish-Subscribe Developers Guide.
See Also
pub.synchronization.latch:closeLatch
pub.synchronization.xref:insertXReference

pub.synchronization.xref:insertXReference
WmPublic. Inserts a cross-reference between a native ID and a canonical key.
Input Parameters
appId

String A unique identier for the resource for which you want to
establish a cross-reference between a native ID and a canonical key.

nativeId

String A unique identier for the resource record with which you
want to establish a cross-reference to canonicalKey .

canonicalKey

String The canonical key with which you want to establish a crossreference to nativeId .

objectId

String A unique identier for the object or process being

synchronized. Typically, the objectId eld is set to the name of the
business process for which you are performing synchronization, such
as "order" or "customer."

Output Parameters
None.
Usage Notes
Use this service on the target side of a synchronization to create a cross-reference
between the new record in the target resource and the canonical document.

webMethods Integration Server Built-In Services Reference Version 9.6

889

Even Header
Synchronization Folder

Most resources generate a unique ID for a new record. Invoke the insertXReference service
after you add the new record in the resource.
After you insert the cross-reference between the new native ID and the canonical key,
use pub.synchronization.latch:closeLatch to close the latch for the record to prevent circular
updates (echoes).
For more information about using the insertXReference service in synchronizations, see the
Publish-Subscribe Developers Guide.
See Also
pub.synchronization.latch:closeLatch
pub.synchronization.xref:createXReference

webMethods Integration Server Built-In Services Reference Version 9.6

890

Odd Header
Trigger Folder

36 Trigger Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

892

891

Even Header
Trigger Folder

You can use the services in the trigger folder to create and delete webMethods
messaging trigger and JMS triggers. You can also use services to manage document
retrieval and document processing for individual webMethods messaging triggers and
change the state of one or more JMS triggers.
Note: A webMethods messaging trigger is a trigger that subscribes to and processes
documents published to a webMethods messaging provider (webMethods Broker or
webMethods Universal Messaging) or published locally within the Integration Server. A
JMS trigger is a trigger that receives messages from a Destination (queue or topic) on a
JMS provider and then processes those messages.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.trigger:createJMSTrigger

WmPublic. Creates a JMS trigger.

pub.trigger:createTrigger

WmPublic. Creates a webMethods

messaging trigger.

pub.trigger:deleteJMSTrigger

WmPublic. Deletes a JMS trigger.

pub.trigger:deleteTrigger

WmPublic. Deletes a webMethods

messaging trigger.

pub.trigger:disableJMSTriggers

WmPublic. Disables one or more JMS

triggers.

pub.trigger:enableJMSTriggers

WmPublic. Enables one or more JMS

triggers.

pub.trigger:resourceMonitoringSpec

WmPublic. Specication for the signature of

a resource monitoring service.

pub.trigger:resumeProcessing

WmPublic. Resumes document processing

for the specied webMethods messaging
trigger.

pub.trigger:resumeRetrieval

WmPublic. Resumes retrieval of documents

from the messaging provider for a specic
webMethods messaging trigger.

webMethods Integration Server Built-In Services Reference Version 9.6

892

Odd Header
Trigger Folder

Element

Package and Description

pub.trigger:suspendJMSTriggers

WmPublic. Suspends one or more JMS

triggers.

pub.trigger:suspendProcessing

WmPublic. Suspends document processing

for the specied webMethods messaging
trigger.

pub.trigger:suspendRetrieval

WmPublic. Suspends retrieval of

documents from the messaging provider for
a specic webMethods messaging trigger.

pub.trigger:createJMSTrigger
WmPublic. Creates a JMS trigger.
Input Parameters
triggerName

String Fully qualied name for the JMS new trigger. Names use any
combination of leers, and/or the underscore character. Make sure
to specify the name of the folder and subfolder in which you want
to save the JMS trigger.
Note: For a list of reserved words and symbols for element names, see
webMethods Service Development Help.

package

String Name of the package in which you want to save the trigger.

aliasName

String Name of the JMS connection alias that you want this JMS
trigger to use to receive messages from the JMS provider.
The JMS connection alias must already exist at the time this service
executes. Although a JMS connection alias does not need to be
enabled at the time you create the JMS trigger, the JMS connection
alias must be enabled for the JMS trigger to execute at run time.
A transacted JMS connection alias cannot be assigned to a JMS
trigger if a cluster policy is applied to the connection factory used
by the JMS connection alias.

jmsTriggerType

String Type of JMS trigger. Specify:

Standard to create a standard JMS trigger. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

893

Even Header
Trigger Folder

SOAPJMS to create a SOAP-JMS trigger.

properties

Document Optional. Properties that you want to assign to the JMS

trigger.
Key

Description

enabled

String Flag indicating whether the new JMS

trigger is enabled or disabled. Set to:
true to create the JMS trigger in an

enabled state.

false to create the JMS trigger in a

disabled state. This is the default.

joinTimeout

String Optional. Number of milliseconds

Integration Server waits for additional
messages to fulll the join. Integration
Server starts the join time-out period when
it receives the rst message that satises the
join.
Set joinTimeout to -1 to indicate that the join
condition never expires.
The default is one day (86400000
milliseconds).
You need to specify a joinTimeout only when
the joinType is AND or XOR. You do not need
to specify a join time-out for an OR join.
Note: You can specify a joinTimeout for a
standard JMS trigger only. SOAP-JMS triggers
cannot have joins.

joinType

String Species the join type for this

standard JMS trigger. The join type
indicates whether Integration Server needs
to receive messages from all, any, or only
one of destinations to execute the trigger
service.
You only need to set joinType if the JMS
trigger receives messages from multiple
destinations.
Note: You can specify a joinType for a standard
JMS trigger only. SOAP-JMS triggers can

webMethods Integration Server Built-In Services Reference Version 9.6

894

Odd Header
Trigger Folder

receive messages from one destination only

and therefore cannot have joins.
Set to:
N/A to indicate that this JMS trigger does

not have a join. That is, the JMS trigger

receives messages from one Destination
only.

AND to invoke the trigger service when the

standard JMS trigger receives a message

from every destination within the join
time-out period. The messages must have
the same activation.

For more information about activation IDs,

see Using webMethods Integration Server to
Build a Client for JMS.
OR to invoke the trigger service when the

standard JMS trigger receives a message

from any of the specied destinations.

Note: Using an Any (OR) join is similar

to creating multiple JMS triggers that
listen to dierent destinations. While a
JMS trigger with an Any (OR) join will
use fewer resources (a single thread will
poll each destination for messages), it may
cause a decrease in performance (it may
take longer for one thread to poll multiple
destinations).
XOR to invoke the trigger service when

it receives a message from any of the

specied destinations. For the duration of
the join time-out period, the Integration
Server discards any messages with the
same activation that the trigger receives
from the specied destinations.
maxRetryAempts

String Optional. Maximum number of times

Integration Server should re-execute the
trigger service when the trigger service
ends because of a transient error that causes
an ISRuntimeException. The default is 0
aempts (indicating the trigger service does
not retry)

webMethods Integration Server Built-In Services Reference Version 9.6

895

Even Header
Trigger Folder

Note: maxRetryAempts applies to nontransacted JMS triggers only.

retryInterval

String Optional. Length of time Integration

Server waits between retry aempts. The
default is 10 seconds.
Note: retryInterval applies to non-transacted
JMS triggers only.

onTransientError

String Flag indicating how Integration Server

handles transient errors for the JMS trigger.
For a non-transacted JMS trigger, indicates
how Integration Server handles a retry
failure for a JMS trigger. A retry failure
occurs when Integration Server reaches the
maximum number of retry aempts and
the trigger service still fails because of an
ISRuntimeException.
For a transacted JMS trigger, indicates
how Integration Server handles a transient
error that occurs during service execution,
resulting in the entire transaction being
rolled back.
Specify one of the following:
Throw Exception/ Recover Only

This is the default.

For a non-transacted JMS trigger,
indicate that Integration Server throws
a service exception when the last
allowed retry aempt ends because of an
ISRuntimeException.
For a transacted JMS trigger, indicate that
Integration Server recovers the message
back to the JMS provider. Integration
Server receives the message again almost
immediately.
Suspend and Retry Later/ Suspend
and Recover

For a non-transacted JMS trigger, indicate

that Integration Server suspends the
trigger when the last allowed retry aempt
webMethods Integration Server Built-In Services Reference Version 9.6

896

Odd Header
Trigger Folder

ends because of an ISRuntimeException.

Integration Server retries the trigger
service at a later time when the resources
needed by the trigger service become
available.
For a transacted JMS trigger, indicate
that Integration Server suspends the JMS
trigger and then recovers the message back
to the JMS provider. Integration Server
executes the trigger service at a later time
when the resources needed by the trigger
service become available.
resumeTaskSvcName

String Optional. Fully qualied name of

the service that Integration Server executes
when one of the following occurs:
The trigger service ends because of a
retry failure and onTransientError is set to

Suspend and Retry Later/Suspend and

Recover.

The trigger service is part of a transacted

JMS trigger and onTransientError property
is set to Suspend and Retry Later/
Suspend and Recover.
The document resolver service
used for exactly-once processing
(dupResolverSvcName) ends because
of a run-time exception and the
wa.server.trigger.preprocess.suspendAndRetryOnError
is set to true.
isConcurrent

String Flag indicating whether the JMS

trigger uses a concurrent processing mode
or a serial processing mode. Set to:
true to specify a concurrent processing

mode. Integration Server processes

multiple messages for this trigger at one
time.
false to specify a serial processing mode.

Integration Server processes messages

received by this trigger one after the other.
This is the default.
suspendOnError

String Flag indicating whether Integration

Server suspends the JMS trigger when an

webMethods Integration Server Built-In Services Reference Version 9.6

897

Even Header
Trigger Folder

exception occurs during trigger service

execution. Set to:
true to suspend the trigger when a trigger

service ends with a fatal error.

false to not suspend the JMS trigger

when a trigger service ends with a fatal

error. This is the default.
maxExecutionThreads

String Optional. Maximum number of

messages that Integration Server can
process concurrently on each connection for
this trigger. maxExecutionThreads must be
greater than or equal to connectionCount .
The default is 1.
Note: This seing applies to concurrent JMS
triggers only.
Note: If the JMS provider from which the JMS
trigger retrieves messages does not support
concurrent access by durable subscribers, set
the value of maxExecutionThreads to 1.

maxBatchSize

String Optional. Maximum number of

messages that the trigger service can receive
at one time. If you do not want the trigger
to perform batch processing, leave this
property set to 1. The default is 1.
A transacted JMS trigger can be used for
batch processing if the JMS connection
alias used by the trigger connects to a
JMS provider that supports the reuse
of transacted JMS sessions. If the JMS
provider does not support the reuse of
transacted JMS sessions, set maxBatchSize
to 1. Consult the documentation for your
JMS provider to determine whether or
not the JMS provider supports the reuse
of transacted JMS sessions. Note that
webMethods Broker version 8.2 and higher,
webMethods Universal Messaging version
9.5, and webMethods Nirvana version 7 and
higher support the reuse of transacted JMS
sessions.

webMethods Integration Server Built-In Services Reference Version 9.6

898

Odd Header
Trigger Folder

Note: For a SOAP-JMS trigger the

maxBatchSize must be set to 1.
dupDetection

String Flag indicating whether exactly-once

processing is enabled for the JMS trigger.
Set to:
true to specify that exactly-once

processing is provided for messages

received by this trigger.
false to specify that exactly-once

processing is not provided for messages

received by this trigger. This is the default.
dupHistory

String Flag indicating whether a document

history database will be maintained and
used to determine whether a message is a
duplicate. Set to:
true to indicate that Integration Server

uses a document history database as part

of exactly-once processing.

false to indicate that Integration Server

does not use a document history database

as part of exactly-once processing. This is
the default.

dupHistoryTTL

String Optional Number of milliseconds that

the document history database maintains
an entry for a document processed by this
trigger.
The default is 2 hours (7200000
milliseconds).

dupResolverSvcName

String Optional. Species the service that

you created to determine whether message's
status is New, Duplicate, or In Doubt.

prefetchSize

String Optional. Species the maximum

number of messages Integration Server
aempts to retrieve for this JMS trigger
when it requests more messages from the
webMethods Broker.
The default is 10.

webMethods Integration Server Built-In Services Reference Version 9.6

899

Even Header
Trigger Folder

Note: This parameter applies only when

working with the webMethods Broker as a
JMS provider.
acknowledgeMode

String Indicates how the JMS trigger

acknowledges messages it receives to the
JMS provider.
Note: acknowledgeMode applies to nontransacted JMS triggers only. When creating
a transacted JMS trigger, Integration
Server ignores acknowledgeMode . The JMS
connection alias specied for aliasName
determines whether or not the created trigger
is transacted or non-transacted.
Set to:
CLIENT_ACKNOWLEDGE to acknowledge or

recover the message only after the JMS

trigger processes the message completely.
This is the default.
AUTO_ACKNOWLEDGE to automatically

acknowledge the message when it

is received by the JMS trigger. The
Integration Server will acknowledge the
message before the trigger completes
processing. The JMS provider cannot
redeliver the message if Integration Server
becomes unavailable before message
processing completes.
DUPS_OK_ACKNOWLEDGE to lazily

acknowledge the delivery of messages.

This may result in the delivery of duplicate
messages.
executeUser

String Optional. Name of the user account

whose credentials Integration Server uses
to execute a service associated with the JMS
trigger. You can specify a locally dened
user account or a user account dened in a
central or external directory. The default is
Administrator.

connectionCount

String Optional. Species the number of

connections a concurrent JMS trigger can
use to retrieve messages from the JMS

webMethods Integration Server Built-In Services Reference Version 9.6

900

Odd Header
Trigger Folder

provider. connectionCount must be less

than or equal to maxExecutionThreads . The
default is 1.
Note: connectionCount applies only when the
JMS connection alias specied for aliasName is
congured to create a separate connection for
each JMS trigger.
Note: When using multiple connections to
the webMethods Broker acting as the JMS
provider, Integration Server uses a dierent
client ID for each JMS trigger that uses
the JMS connection alias. However, when
Integration Server connects to other JMS
providers, it uses the same client ID for each
connection. Some JMS providers do not
permit multiple connections to use the same
client ID to retrieve messages from a Topic
with a durable subscriber. Review the JMS
provider documentation before conguring
the use of multiple connections for a JMS
connection alias and any concurrent JMS
triggers that use the JMS connection alias.
destinations

Document List Destinations from which the JMS trigger receives

messages.
Note: For a SOAP-JMS trigger, you can specify one destination only.
Key

Description

destination

String Name or lookup name of the

Destination from which you want the JMS
trigger to receive messages.
Specify the lookup name of the Destination
object when the JMS connection alias uses
JNDI to retrieve administered objects.
Specify the provider-specic name of the
Destination when the JMS connection alias
uses the native webMethods API to connect
directly to the webMethods Broker.

destinationType

String Optional. Type of destination from

which the JMS trigger receives messages. Set
to:

webMethods Integration Server Built-In Services Reference Version 9.6

901

Even Header
Trigger Folder

Queue to specify that the destination is a

queue. This is the default.

Topic to specify that the destination is a

topic.
messageSelector

String Optional. Filter used to receive a

subset of messages from the specied
destination. A message selector allows a client
to lter the messages it wants to receive
by use of a SQL92 string expression in the
message header. That expression is applied
to properties in the message header (not to
the message body content) containing the
value to be ltered.

durableSubscriber
Name

String Optional. Name of the durable

subscriber that you want to create for this
JMS trigger on the JMS provider. A durable
subscriber creates a durable subscription on
the JMS provider. A durable subscription
allows the subscriber to receive all the
messages published on a topic, including
those published while the subscriber is
inactive.
Note: durableSubscriberName applies when
destinationType is set to Topic only.

durableSubscriber
NoLocal

String Optional. Flag indicating whether the

JMS trigger ignores messages sent by the
same Integration Server on which the JMS
trigger resides.
Set to:
true to indicate that the JMS trigger

ignores messages sent by the same

Integration Server on which the JMS
trigger resides.
false to indicate that the JMS trigger

receives and processes messages sent by

the same Integration Server on which the
JMS trigger resides. This is the default.
Note: durableSubscriberNoLocal applies when
destinationType is set to Topic only.

webMethods Integration Server Built-In Services Reference Version 9.6

902

Odd Header
Trigger Folder

Note: If the JMS connection alias specied

for this trigger has the Create New Connection
per Trigger option enabled, then set
durableSubscriberNoLocal to false. For the JMS
trigger to ignore locally published messages,
the publisher and subscriber must share the
same connection. When the JMS connection
alias uses multiple connections per trigger,
the publisher and subscriber will not share the
same connection.
routingRules

Document List Optional. Routing rules for messages received by this

standard JMS trigger.
Note: You only need to specify routing rules for standard JMS triggers.
SOAP-JMS triggers do not use routing rules.
Key

Description

ruleName

String Name for the routing rule.

serviceName

String Fully qualied name of the service

Integration Server invokes when it receives
a message from one of the specied
destinations.

lter

String Optional. Filter that you want

Integration Server to apply to messages
the JMS trigger receives. A lter species
criteria for the contents of the message
body. Integration Server applies a local lter
to message after the JMS trigger receives the
message from the JMS provider.

Note: Integration Server evaluates the routing rules in the same order
in which the rules appear in the routingRules document list. It is
possible that a message could satisfy more than one routing rule.
However, Integration Server executes only the service associated
with the rst satised routing rule and ignores the remaining
routing rules. Therefore, the order in which you list routing rules is
important.
Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

903

Even Header
Trigger Folder

Usage Notes
You can use pub.trigger:createJMSTriggers to create standard JMS triggers or SOAP-JMS
triggers.
Even though WS endpoint triggers are SOAP-JMS triggers, you can create WS endpoint
triggers via Integration Server Administrator only. For more information about WS
endpoint triggers, see webMethods Integration Server Administrators Guide.
If you use a JNDI provider to store JMS administered objects, the Connection Factories
and Destinations (queues and topics) that you want this JMS trigger to use to consume
messages must already exist. If they do not exist, the JMS trigger will be created but
will not start. The JMS trigger will appear disabled in Designer and Integration Server
Administrator.
If you use the native webMethods API to connect directly to the webMethods Broker, the
Destinations from which you want the JMS trigger to receive messages must exist on the
Broker. However, if you intend to use a durable subscriber to receive messages, it can be
created by Integration Server when the pub.trigger:createJMSTrigger executes successfully.
For more information about creating Destinations on the Broker, see Administering
webMethods Broker.
The transaction type of the JMS connection alias determines whether or not the JMS
trigger is transacted (that is, it receives and processes messages as part of a transaction).
Transacted JMS triggers have slightly dierent properties and operate dierently than
non-transacted JMS triggers.
For a standard JMS trigger, the trigger service that you want to specify in the routing
rule must already exist on the same Integration Server on which you create the JMS
trigger.
A standard JMS trigger can contain multiple routing rules. Each routing rule must have
a unique name.
A standard JMS trigger that contains an All (AND) or Only one (XOR) join can only have
one routing rule and cannot have a batch processing size (Max batch messages property)
greater than 1. A standard JMS trigger with an Any (Or) join can have multiple routing
rules.
When you select Topic as the destinationType and specify a value for
durableSubscriberName , Integration Server creates a a durable subscriber for the JMS
trigger on the JMS provider. A durable subscriber establishes a durable subscription
with a unique identity on the JMS provider. A durable subscription allows subscribers
to receive all the messages published on a topic, including those published while the
subscriber is inactive (for example, if the JMS trigger is disabled). When the associated
JMS trigger is disabled, the JMS provider holds the messages in nonvolatile storage. If
a durable subscription already exists for the specied durable subscriber on the JMS
provider, this service resumes the subscription.
When you select Topic as the destinationType , but do not specify a durable subscriber
name, Integration Server creates a non-durable subscriber for the JMS trigger. A nondurable subscription allows subscribers to receive messages on their chosen topic only if

webMethods Integration Server Built-In Services Reference Version 9.6

904

Odd Header
Trigger Folder

the messages are published while the subscriber is inactive. A non-durable subscription
lasts the lifetime of its message consumer. Note that non-durable subscribers cannot
receive messages in a load-balanced fashion.
Integration Server uses a consumer to receive messages for a JMS trigger. This consumer
encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.
Triggers and services can both be congured to retry. When a standard trigger invokes
a service (that is, the service functions as a trigger service), Integration Server uses the
trigger retry properties instead of the service retry properties. For a SOAP-JMS trigger,
Integration Server uses the retry properties of the SOAP-JMS trigger instead of the retry
properties of the service used as an operation in the web service descriptor.
When Integration Server retries a trigger service and the trigger service is congured to
generate audit data on error, Integration Server adds an entry to the audit log for each
failed retry aempt. Each of these entries will have a status of "Retried" and an error
message of "Null". However, if Integration Server makes the maximum retry aempts
and the trigger service still fails, the nal audit log entry for the service will have a status
of "Failed" and will display the actual error message. Integration Server makes the audit
log entry regardless of which retry failure option the trigger uses.
Integration Server generates the following journal log message between retry aempts:
[ISS.0014.0031D] Service serviceName failed with ISRuntimeException.
Retry x of y will begin in retryInterval milliseconds.

If you do not congure service retry for a trigger, set the maxRetryAempts to 0. Because
managing service retries creates extra overhead, seing this property to 0 can improve
the performance of services invoked by the trigger.
You can invoke the pub.flow:getRetryCount service within a trigger service to determine
the current number of retry aempts made by Integration Server and the maximum
number of retry aempts allowed for the trigger service. For more information about
the pub.flow:getRetryCount service, see the webMethods Integration Server Built-In Services
Reference.
Before a standard JMS trigger can be enabled, the trigger service must already exist on
the same Integration Server.
The signature for a standard JMS trigger service must reference one of the following
specications:
Use pub.jms:triggerSpec as the specication reference if the trigger service will process
one message at a time.
Use pub.jms:batchTriggerSpec as the specication reference if the trigger service will
process multiple messages at one time. That is, the trigger service will receive a
batch of messages as input and process all of those messages in a single execution. A
trigger that receives and processes a batch of messages is sometimes referred to as a
batch trigger.
If you create a concurrent JMS trigger that uses multiple connections to receive messages
from the JMS provider, (you specied a value greater than 0 for connectionCount ), keep
the following points in mind:

webMethods Integration Server Built-In Services Reference Version 9.6

905

Even Header
Trigger Folder

The JMS connection alias associated with this trigger must be congured to create an
individual connection for each trigger. That is, the Create New Connection per Trigger
option must be set to Yes for the JMS connection alias.
If the JMS connection alias species a connection to the webMethods Broker, the
following must be true:
The webMethods Broker must be webMethods Broker version 7.1 or higher.
The versions of following three Broker jar les installed on Integration Server
must be the 8.0 SP1 or higher versions of the les.
Software AG_directory/common/lib/wm-jmsclient.jar
Software AG_directory/common/lib/wm-brokerclient.jar
Software AG_directory/Integration Server_directory/instances/instance_name /lib/
jars/wm- jmsnaming.jar
The JMS trigger must be congured for concurrent processing (isConcurrent is set
to true). You cannot use multiple connections with JMS triggers that perform serial
processing.
The JMS trigger must receive messages from Queues or from Topics using a durable
subscriber. You cannot use multiple connections with JMS triggers that receive
messages from Topics using a non-durable subscriber.
The connectionCount value must be less than or equal to the maxExecutionThreads
value.
SOAP-JMS triggers do not use routing rules. For SOAP-JMS triggers, Integration Server
processes the SOAP message contained in the JMS message by executing an operation in
a web service descriptor.
To use a SOAP-JMS trigger as a listener for provider web service descriptors, do the
following:
Create a provider web service endpoint alias for the JMS transport in which the
SOAP-JMS trigger is specied as the JMS trigger that acts as a listener.
Assign the web service endpoint alias to the JMS binder in the web service descriptor
for which you want the SOAP-JMS trigger to listen for messages.
For more information about creating JMS triggers, see webMethods Service Development
Help.
See Also
pub.trigger:deleteJMSTrigger
pub.jms:triggerSpec
pub.jms:batchTriggerSpec

webMethods Integration Server Built-In Services Reference Version 9.6

906

Odd Header
Trigger Folder

pub.trigger:createTrigger
WmPublic. Creates a webMethods messaging trigger.
Note: The pub.trigger:createTrigger service cannot be used to create webMethods messaging
triggers that subscribe to document types published to Universal Messaging.
Input Parameters
triggerName

String Fully qualied name for the new trigger that uses any
combination of leers, and/or the underscore character. Make
sure to specify the name of the folder and subfolder in which
you want to save the trigger.
Note: For a list of reserved words and symbols for element
names, see webMethods Service Development Help.

package

String Name of the package in which you want to save the

trigger.

properties

Document Optional. Properties that you want to assign to the

trigger.
Key

Description

joinTimeOut

String Number of milliseconds

Integration Server waits for the other
documents in the join condition.
Integration Server starts the join
time-out period when it pulls the
rst document that satises the join
condition from the trigger queue.
You need to specify a join time-out
only when your condition is an AND
or XOR join type. You do not need to
specify a join time-out for an OR join
condition or a condition that does not
use joins.
Set joinTimeOut to -1 to indicate that
the join condition never expires.
The default is 1 day.

webMethods Integration Server Built-In Services Reference Version 9.6

907

Even Header
Trigger Folder

queueCapacity

String Maximum number of

documents that Integration Server
maintains in the queue for this trigger.
The default is 10.

queueRellLevel

String Number of unprocessed

documents that must remain in the
trigger queue before Integration
Server retrieves more documents for
the trigger from the Broker.
The default is 4.
The queueRellLevel value must be
less than or equal to the queueCapacity
value.

ackQueueSize

String Maximum number of pending

document acknowledgments for the
trigger. The value must be greater
than zero.
The default is 1.

maxRetryAempts

String Maximum number of times

Integration Server should aempt to
re-execute the trigger service. If you
want the trigger service to retry until
it executes successfully, specify -1.
The default is 5 retries.

retryInterval

String Number of seconds Integration

Server waits between retry aempts.
The default is 10 seconds.

onRedeliveryFailure

String Species how Integration Server

handles retry failure for the trigger.
Retry failure occurs when Integration
Server reaches the maximum number
of retry aempts and the trigger
service still fails because of a run-time
exception.
Specify one of the following values:
Throw Exception to indicate that

Integration Server throws a service

exception when the last allowed
webMethods Integration Server Built-In Services Reference Version 9.6

908

Odd Header
Trigger Folder

retry aempt ends because of a runtime exception.

This is the default.
Suspend and Retry Later to

indicate that Integration Server

suspends the trigger when the last
allowed retry aempt ends because
of a run-time exception. Integration
Server retries the trigger service at a
later time.
Note: If you set onRedeliveryFailure
to Suspend and Retry later,
you must specify a service for the
resumeTaskSvcName parameter. If
you do not specify a service and the
trigger suspends because of retry
failure, Integration Server will not
resume the trigger automatically.
You must resume the trigger
manually.
resumeTaskSvcName

String Fully qualied name of the

service that Integration Server
executes when one of the following
occurs:
During exactly-once processing,
the document resolver service
ends because of a transient error.
Integration Server suspends
the trigger and invokes the
resumeTaskSvcName to determine
when the resources associated with
the document resolver service are
available. After the resources become
available, Integration Server resumes
document retrieval and document
processing for the trigger.
A trigger ends because of retry
failure and the onRedeliveryFailure
variable is set to Suspend and
Retry Later. Integration Server
executes the resumeTaskSvcName to
determine whether the resources
associated with a trigger service
are available. If the resources are

webMethods Integration Server Built-In Services Reference Version 9.6

909

Even Header
Trigger Folder

available, Integration Server resumes

document retrieval and document
processing for the trigger.
isPriorityEnabled

Boolean Indicates whether the

trigger receives messages in order
of priority or in the order in which
they are published. Specify one of the
following values:
true to indicate that documents

should reach the trigger in order of

priority. The higher the priority the
faster the document will be received.
false to indicate that documents

should reach the trigger in the order

in which they are published. This is
the default.
A trigger ends because of retry
failure and the onRedeliveryFailure
variable is set to Suspend and
Retry Later. Integration Server
executes the resumeTaskSvcName to
determine whether the resources
associated with a trigger service
are available. If the resources are
available, Integration Server resumes
document retrieval and document
processing for the trigger.
isConcurrent

String Indicates whether the trigger

uses a concurrent processing mode or
a serial processing mode. Specify one
of the following values:
true to specify a concurrent

processing mode. Integration Server

processes as many documents in the
trigger queue as it can at once.
false to specify a serial processing

mode. Integration Server processes

documents in the trigger queue one
after the other. This is the default.
serialSuspendOnError

String Indicates whether Integration

Server suspends document processing

webMethods Integration Server Built-In Services Reference Version 9.6

910

Odd Header
Trigger Folder

and document retrieval automatically

when a trigger service ends with an
error. Set to:
true to indicate that Integration

Server suspends the trigger

automatically if an error occurs
during trigger service execution.
false to indicate that Integration

Server should not suspend a trigger

if an error occurs during trigger
service execution. This is the default.
maxExecutionThreads

String Maximum number of

documents that Integration Server can
process concurrently for this trigger.
Integration Server uses one server
thread to process each document in
the trigger queue.

dupDetection

String Indicates whether Integration

Server performs exactly-once
processing for guaranteed documents
received by this trigger. Set to:
true to indicate that Integration

Server performs exactly-once

processing for guaranteed
documents received by this trigger.
false to indicate that exactly-once

processing is not performed. This is

the default.
dupHistory

String Indicates whether Integration

Server uses a document history
database as part of performing
exactly-once processing. Set to:
true to indicate that Integration

Server uses a document history

database as part of exactly-once
processing.

false to indicate that Integration

Server does not use a document

history database as part of exactlyonce processing. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

911

Even Header
Trigger Folder

dupHistoryTTL

String Number of milliseconds that the

document history database maintains
an entry for a document processed by
this trigger.
The default is 2 hours.

dupResolverSvcName

conditions

String Fully qualied name of the

service used to determine conclusively
whether a document's status is New,
Duplicate, or In Doubt.

Document List Optional. Species the conditions for the trigger.

A condition associates one or more publishable document
types with a single service. The publishable document type
acts as the subscription piece of the trigger. The service is
the processing piece. When the trigger receives documents
to which it subscribes, the Integration Server processes the
document by invoking the service specied in the condition.
Triggers can contain multiple conditions; however, a trigger
can contain only one join condition.
Note: The order in which you list conditions in the conditions list
is important because it indicates the order in which Integration
Server evaluates the conditions at run time. When Integration
Server receives a document, it invokes the service specied
in the rst condition that is satised by the document. The
remaining conditions are ignored. For more information about
the order in which conditions are evaluated, see the PublishSubscribe Developers Guide.
Key

Description

conditionName

String Name you want to assign to the

condition.
By default, Integration Server assigns
each condition a default name such as
Condition1 or Condition2.

serviceName

String Fully qualied name of the

service that to be invoked when
the trigger receives documents or
messages to which it subscribes.

joinType

String The join type for the condition.

The join type determines whether
Integration Server needs to receive all,

webMethods Integration Server Built-In Services Reference Version 9.6

912

Odd Header
Trigger Folder

any, or only one of the documents or

messages in the condition to execute
the trigger service.
Only webMethods messaging triggers
that receives documents from Broker
can contain join conditions.
You must specify a joinType if the
condition subscribes to more than
one document type or message. That
is, if messageTypeFilterPairs contains
more than one pair, you must select a
joinType . Specify one of the following:
N/A to indicate this is not a join

condition.

AND to indicate that Integration

Server invokes the trigger service

when the server receives an instance
of each specied message type
within the join time-out period. The
instance documents must have the
same activation ID.
This is the default join type.
OR to indicate that Integration Server

invokes the associated trigger service

when it receives an instance of any
one of the specied publishable
document types.

XOR to indicate that Integration

Server invokes the associated trigger

service when it receives an instance
of any of the specied document
types. For the duration of the join
time-out period, Integration Server
discards (blocks) any instances of
the specied publishable document
types with the same activation ID.
messageTypeFilterPairs

Document List Species the messages

and document types to which a
trigger subscribes and the lter that
must be applied to instances of the
message or document type
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

913

Even Header
Trigger Folder

messageType

String Fully
qualied
name of the
publishable
document type
or message to
which the trigger
subscribes.

lter

String Filter
that you want
Integration
Server to apply
to each instance
of this message.
Integration
Server executes
the trigger
service only
if instances of
the message
meet the lter
criteria. Filters
are optional for a
trigger condition.
For more
information
about lters,
see the PublishSubscribe
Developers Guide.
Note: If multiple
conditions in the
trigger specify the
same document
type or message,
the lter must be
the same in the
conditions. If the
lters are not the
same, Integration
Server ignores the
condition.

webMethods Integration Server Built-In Services Reference Version 9.6

914

Odd Header
Trigger Folder

Note: If you specify multiple

messageType values in one condition,
you need to select a joinType .
Output Parameters
None.
Usage Notes
The client executing this service must have write access to the folders and packages in
which the client wants to save the new webMethods messaging trigger. If the client does
not have write access, Integration Server throws a write permissions error. For more
information about assigning access permissions to folders and packages, see webMethods
Service Development Help.
If the trigger subscribes to one or more publishable document types that specify a Broker
connection alias, one of the following occurs when the pub.trigger:createTrigger service
executes:
If the Broker connection alias is enabled, Integration Server registers the trigger
subscription with the Broker by creating a client for the trigger on the Broker.
Integration Server also creates a subscription for each messageType specied in the
trigger conditions and saves the subscriptions with the trigger client.
If the Broker connection alias is not enabled, the trigger will only receive documents
published locally. When you reconnect to a Broker, the next time Integration Server
restarts, Integration Server will create a client for the trigger on the Broker and create
subscriptions for the publishable document types identied in the trigger conditions.
Broker validates the lters in the trigger conditions when Integration Server creates
the subscriptions.
If messageType species a publishable document type that does not exist on the Broker
(that is, there is no associated Broker document type), Integration Server still creates the
trigger client on the Broker, but does not create any subscriptions. Integration Server
creates the subscriptions when you synchronize (push) the publishable document type
with the Broker.
Note: You can also restart a trigger by starting and stopping the messaging connection
alias used by the publishable document type to which the trigger subscribes.
For more information about creating webMethods messaging triggers, see webMethods
Service Development Help.
See Also
pub.trigger:deleteTrigger

webMethods Integration Server Built-In Services Reference Version 9.6

915

Even Header
Trigger Folder

pub.trigger:deleteJMSTrigger
WmPublic. Deletes a JMS trigger.
Input Parameters
triggerName

String Fully qualied name of the JMS trigger to delete.

Output Parameters
None
See Also
pub.trigger:createJMSTrigger

pub.trigger:deleteTrigger
WmPublic. Deletes a webMethods messaging trigger.
Input Parameters
triggerName

String Fully qualied name of the webMethods messaging

trigger that you want to delete.

Output Parameters
None.
Usage Notes
The trigger must be unlocked for this service to execute successfully. If the trigger is
locked when this service executes, Integration Server throws an error stating "Trigger is
locked, change not permied."
When you delete a webMethods messaging trigger that uses a Broker connection alias
that species a shared client prex, deleting the trigger will not delete the corresponding
client queue on the Broker. When the client prex is shared, the client queue might
be used by other Integration Servers. The publishable document type to which a
webMethods messaging trigger subscribes determines the connection alias used by the
trigger.
When you delete a webMethods messaging trigger that uses a Universal Messaging
connection alias that species a shared client prex, deleting the trigger will not delete
the corresponding NamedObject. When the client prex is shared, the NamedObject

webMethods Integration Server Built-In Services Reference Version 9.6

916

Odd Header
Trigger Folder

might be used by other Integration Servers. The publishable document type to which a
webMethods messaging trigger subscribes determines the connection alias used by the
trigger.
See Also
pub.trigger:createTrigger

pub.trigger:disableJMSTriggers
WmPublic. Disables one or more JMS triggers.
Input Parameters
triggerNameList

String List Species the JMS triggers that you want to disable.

applyChangeAcross
Cluster

String Optional. Flag indicating whether the specied JMS

triggers should be disabled across all the servers in the cluster.
Set to:
true to disable the specied JMS triggers on all the nodes in

the cluster.

Note: To make the state change on all the servers in a cluster,

Integration Server must be congured to synchronize trigger
changes across the cluster. For more information about
conguring an Integration Server to synchronize trigger
management changes across a cluster, see webMethods
Integration Server Administrators Guide.
false to disable the JMS triggers on the local Integration
Server only. This is the default.

Output Parameters
None.
Usage Notes
When a JMS trigger is disabled, the JMS trigger is stopped. Integration Server neither
retrieves nor processes messages for the JMS trigger. The JMS trigger remains in this
state until you enable the trigger.
When you disable a JMS trigger that has a non-durable subscriber, the JMS provider will
remove any messages for the JMS trigger.

webMethods Integration Server Built-In Services Reference Version 9.6

917

Even Header
Trigger Folder

If you disable a SOAP-JMS trigger that acts as a listener for one or more provider web
service descriptors, Integration Server will not retrieve any messages for those web
service descriptors.
When you disable a JMS trigger, Integration Server does the following:
If the JMS trigger is waiting before making a retry aempt, Integration Server
interrupts processing for the JMS trigger.
If the JMS trigger is currently processing messages, Integration Server waits a
specied amount of time before forcing the JMS trigger to stop processing messages.
If it does not complete in the alloed time the message consumer used to receive
messages for the JMS trigger is stopped and the JMS session is closed. At this point
the server thread for the JMS trigger continues to run to completion. However, the
JMS trigger will not be able to acknowledge the message when processing completes.
If the message is guaranteed (PERSISTENT), this can lead to duplicate messages.
The time Integration Server waits between the request to disable
the JMS trigger and forcing the trigger to stop is specied by the
watt.server.jms.trigger.stopRequestTimeout property
Because administered objects, like destinations, are congured outside of Integration
Server, disabling a JMS trigger has no impact on the subscription.
Use the pub.trigger:enableJMSTriggers service to enable one or more JMS triggers.
Use the pub.trigger:suspendJMSTriggers service to suspend one or more JMS triggers.
You can also use the Settings > Messaging > JMS Trigger Management screens in Integration
Server Administrator to disable, enable, and suspend JMS triggers. For more
information, see webMethods Integration Server Administrators Guide.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

If Integration Server cannot update the Integration Servers in the cluster because the
change could not be made locally, the Integration Server Administrator displays the
following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors are
resolved.)

webMethods Integration Server Built-In Services Reference Version 9.6

918

Odd Header
Trigger Folder

If Integration Server cannot update the other Integration Servers in the cluster
because cluster synchronization is not congured, the Integration Server writes the
following server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

See Also
pub.trigger:enableJMSTriggers
pub.trigger:suspendJMSTriggers

pub.trigger:enableJMSTriggers
WmPublic. Enables one or more JMS triggers.
Input Parameters
triggerNameList

String List Species the JMS triggers that you want to enable.

applyChangeAcross
Cluster

String Optional. Flag indicating whether the specied JMS

triggers should be enabled across all the servers in the cluster.
Set to:
true to enable the specied JMS triggers on all the nodes in

the cluster.

Note: To make the state change on all the servers in a cluster,

the Integration Server must be congured to synchronize
trigger changes across the cluster. For more information
about conguring an Integration Server to synchronize
trigger management changes across a cluster, see webMethods
Integration Server Administrators Guide.
false to enable the JMS triggers on the local Integration

Server only. This is the default.

Output Parameters
None.
Usage Notes
When a JMS trigger is enabled, the JMS trigger is running and connected to the JMS
provider. Integration Server retrieves and processes messages for the JMS trigger.

webMethods Integration Server Built-In Services Reference Version 9.6

919

Even Header
Trigger Folder

You can also use the Settings > Messaging > JMS Trigger Management screens in Integration
Server Administrator to disable, enable, and suspend JMS triggers. For more
information, see webMethods Integration Server Administrators Guide.
You can use the pub.trigger:disableJMSTriggers service to disable one or more JMS triggers.
Use the pub.trigger:suspendJMSTriggers service to suspend one or more JMS triggers.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

If Integration Server cannot update the Integration Servers in the cluster because the
change could not be made locally, the Integration Server Administrator displays the
following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors
are resolved.)

If the Integration Server cannot update the Integration Servers in the cluster because
cluster synchronization is not congured, the Integration Server writes the following
server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

You can use the Integration Server Administrator to view and change cluster
synchronization status for triggers. For more information, see webMethods Integration
Server Administrators Guide.
See Also
pub.trigger:disableJMSTriggers
pub.trigger:suspendJMSTriggers

pub.trigger:resourceMonitoringSpec
WmPublic. Specication for the signature of a resource monitoring service.
Input Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

920

Odd Header
Trigger Folder

Output Parameters
isAvailable

String Indicates whether the resources needed by the trigger

(webMethods messaging trigger or JMS) to perform exactlyonce processing or to execute the trigger service are available.
The value of this eld determines whether Integration Server
resumes the trigger or re-executes the resource monitoring
service. Integration Server continues to execute a resource
monitoring service until the value of isAvailable is "true". The
isAvailable eld must have one of the following values:
true to indicate that the resources associated with the

trigger are available. For a webMethods messaging trigger,

Integration Server resumes document retrieval and document
processing for the trigger. For a JMS trigger, Integration
Server enables the trigger.
false to indicate that the resources associated with the

trigger are not available. Integration Server will not resume

the trigger.
Usage Notes
The pub.trigger:resourceMonitoringSpec must be used as the service signature for any service
used as a resource monitoring service. A resource monitoring service determines whether
the resources associated with a trigger (webMethods messaging trigger or JMS) are
available for exactly-once processing or document pre-processing. Integration Server
executes a resource monitoring service after retry failure occurs for the trigger or
when the document resolver service fails because of a run-time exception. For more
information about building a resource monitoring service, see the Publish-Subscribe
Developers Guide.

pub.trigger:resumeProcessing
WmPublic. Resumes document processing for the specied webMethods messaging
trigger.
Input Parameters
triggerName

String Fully qualied name of the webMethods messaging

trigger for which you want to resume document processing.

persistChange

String Optional. Flag indicating whether the document

processing change should be permanent or temporary. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

921

Even Header
Trigger Folder

true to save the change to le. Integration Server persists

the change across server restarts, package reloads, and

changes to trigger properties. The trigger will continue to
process documents until it is actively suspended via the
Integration Server Administrator or by execution of the
pub.trigger:suspendProcessing service.

false to indicate that the change is temporary and will not

be maintained when the server restarts, the trigger is enabled

or disabled, or the package containing the trigger reloads.
This is the default.
applyChangeAcross
Cluster

String Optional. Flag indicating whether document processing

should be resumed for this trigger across all the servers in the
cluster. Set to:
true to resume document processing for the specied trigger

on all the nodes in the cluster.

Note: To make the document processing change on all

the servers in a cluster, the Integration Server must be
congured to synchronize trigger changes across the cluster.
For more information about conguring an Integration
Server to synchronize trigger management changes across
a cluster, see webMethods Integration Server Administrators
Guide.
false to indicate that document processing for this trigger

should be resumed on the local Integration Server only. This

is the default.
The applyChangeAcrossCluster parameter applies only to
triggers that receive documents from the Broker.
Output Parameters
None.
Usage Notes
This service aects all documents in the specied trigger queue on the Integration
Server, including documents retrieved from the messaging provider and from local
publishing.
If you do not persist the change, the trigger reverts to the previously saved document
processing state when the Integration Server restarts, the trigger is enabled or disabled,
or the package containing the trigger reloads.
After this service executes, the Integration Server resumes document processing for this
trigger at the percentage specied in the Execution Threads Throttle eld on the Settings

webMethods Integration Server Built-In Services Reference Version 9.6

922

Odd Header
Trigger Folder

> Messaging > webMethods Messaging Trigger Management page in the Integration Server
Administrator.
Integration Server resumes document processing for the specied trigger even if
document processing is suspended for all triggers on the Integration Server (that is, the
Processing State for all triggers is set to Suspended).
Integration Server will not resume document processing for the specied trigger if the
trigger is locked by a user. For more information about locking elements, see webMethods
Service Development Help.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If the Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

If the Integration Server cannot update the Integration Servers in the cluster because
the change could not be made locally, the Integration Server Administrator displays
the following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors are
resolved.)

If the Integration Server cannot update the Integration Servers in the cluster because
cluster synchronization is not congured, the Integration Server writes the following
server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

You can use the Integration Server Administrator to view and change cluster
synchronization status for triggers. For more information, see webMethods Integration
Server Administrators Guide.
In a Java service, you can resume document processing using
com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setProcessingSuspended().
For more information about this method, see the webMethods Integration Server Java API
Referencefor the com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade class.
You can resume and suspend document processing for an individual trigger or
all triggers using the Integration Server Administrator. For more information, see
webMethods Integration Server Administrators Guide.
See Also
pub.trigger:suspendProcessing

webMethods Integration Server Built-In Services Reference Version 9.6

923

Even Header
Trigger Folder

pub.trigger:resumeRetrieval
WmPublic. Resumes retrieval of documents from the messaging provider for a specic
webMethods messaging trigger.
Input Parameters
triggerName

String Fully qualied name of the webMethods messaging

trigger for which you want to resume document retrieval.

persistChange

String Optional. Flag indicating whether the document

retrieval change should be permanent or temporary. Set to:
true to save the change to le. Integration Server persists

the change across server restarts, package reloads, and

changes to trigger properties. The trigger will continue to
retrieve documents until it is actively suspended via the
Integration Server Administrator or by execution of the
pub.trigger:suspendRetrieval service.

false to indicate that the change is temporary and will not

be maintained when the server restarts, the trigger is enabled

or disabled, or the package containing the trigger reloads.
This is the default.
applyChangeAcross
Cluster

String. Optional. Flag indicating whether document retrieval

should be resumed for this trigger across all the servers in the
cluster. Set to:
true to resume document retrieval for the specied trigger

on all the servers in the cluster.

Note: To make the document retrieval change on all

the servers in a cluster, the Integration Server must be
congured to synchronize trigger changes across the cluster.
For more information about conguring an Integration
Server to synchronize trigger management changes across
a cluster, see webMethods Integration Server Administrators
Guide.
false to indicate that document retrieval for this trigger

should be resumed on the local Integration Server only. This

is the default.
The applyChangeAcrossCluster parameter applies only to
triggers that receive documents from the Broker.

webMethods Integration Server Built-In Services Reference Version 9.6

924

Odd Header
Trigger Folder

Output Parameters
None.
Usage Notes
This service does not aect document retrieval for locally published documents to which
this trigger subscribes.
If you do not persist the change, the trigger reverts to the previously saved document
retrieval state when the server restarts, the trigger is enabled or disabled, or the package
containing the trigger reloads.
After this service executes, the Integration Server resumes document retrieval for this
trigger at the percentage specied in the Queue Capacity Throttle eld on the Settings
> Messaging > webMethods Messaging Trigger Management page in the Integration Server
Administrator.
The Integration Server resumes document retrieval for the specied trigger even if
document retrieval is suspended for all the triggers on the Integration Server (that is, the
Retrieval State for all triggers is set to Suspended).
The Integration Server will not resume document retrieval for the specied trigger if the
trigger is locked by a user. For more information about locking elements, see webMethods
Service Development Help.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If the Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

If the Integration Server cannot update the Integration Servers in the cluster because
the change could not be made locally, the Integration Server Administrator displays
the following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors are
resolved.)

If the Integration Server cannot update the Integration Servers in the cluster because
cluster synchronization is not congured, the Integration Server writes the following
server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

webMethods Integration Server Built-In Services Reference Version 9.6

925

Even Header
Trigger Folder

You can use the Integration Server Administrator to view and change cluster
synchronization status for triggers. For more information, see webMethods Integration
Server Administrators Guide.
In a Java service, you can resume document retrieval by calling
com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setRetrievalSuspended().
For more information about this method, see the webMethods Integration Server Java API
Reference for the com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade class.
You can resume and suspend document retrieval for an individual trigger or all triggers
using the Integration Server Administrator. For more information, see webMethods
Integration Server Administrators Guide.
See Also
pub.trigger:suspendRetrieval

pub.trigger:suspendJMSTriggers
WmPublic. Suspends one or more JMS triggers.
Input Parameters
triggerNameList

String List Species the JMS triggers that you want to suspend.

applyChangeAcross
Cluster

String Optional. Flag indicating whether the specied JMS

triggers should be suspended across all the servers in the
cluster. Set to:
true to suspend the specied JMS triggers on all the nodes in

the cluster.

Note: To make the status change on all the servers in a

cluster, the Integration Server must be congured to
synchronize trigger changes across the cluster. For more
information about conguring an Integration Server to
synchronize trigger management changes across a cluster,
see webMethods Integration Server Administrators Guide.
false to suspend the JMS triggers on the local Integration
Server only. This is the default.

Output Parameters
None.

webMethods Integration Server Built-In Services Reference Version 9.6

926

Odd Header
Trigger Folder

Usage Notes
When a JMS trigger is suspended, the JMS trigger is running and connected to the JMS
provider. Integration Server has stopped message retrieval, but continues processing
any messages it has already retrieved. Integration Server enables the JMS trigger
automatically upon server restart or when the package containing the JMS trigger
reloads.
If you suspend a SOAP-JMS trigger that acts as a listener for one or more provider web
service descriptors, Integration Server will not retrieve any messages for those web
service descriptors.
If a JMS trigger is processing messages when this service executes, the JMS trigger will
complete processing. JMS trigger also acknowledges the messages to the JMS provider.
After a suspending a JMS trigger, Integration Server will not start processing for any
additional messages already received by the JMS trigger.
Use the pub.trigger:disableJMSTriggers service to disable one or more JMS triggers.
Use the pub.trigger:enableJMSTriggers service to enable one or more JMS triggers.
You can also use the Settings > Messaging > JMS Trigger Management screens in Integration
Server Administrator to disable, enable, and suspend JMS triggers. For more
information, see webMethods Integration Server Administrators Guide.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

If Integration Server cannot update the Integration Servers in the cluster because the
change could not be made locally, the Integration Server Administrator displays the
following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors
are resolved.)

If Integration Server cannot update the other Integration Servers in the cluster
because cluster synchronization is not congured, the Integration Server writes the
following server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

webMethods Integration Server Built-In Services Reference Version 9.6

927

Even Header
Trigger Folder

See Also
pub.trigger:disableJMSTriggers
pub.trigger:enableJMSTriggers

pub.trigger:suspendProcessing
WmPublic. Suspends document processing for the specied webMethods messaging
trigger.
Input Parameters
triggerName

String Fully qualied name of the webMethods messaging

trigger for which you want to suspend document processing.

persistChange

String Optional. Flag indicating whether the document

processing change should be permanent or temporary. Set to:
true to save the change to le. Integration Server persists

the change across server restarts, package reloads, and

changes to trigger properties. The trigger will not process
documents until processing is actively resumed via the
Integration Server Administrator or by execution of the
pub.trigger:resumeProcessing service.

false to indicate that the change is temporary and will not

be maintained when the server restarts, the trigger is enabled

or disabled, or the package containing the trigger reloads.
This is the default.
applyChangeAcross
Cluster

String Optional. Flag indicating whether document processing

should be suspended for this trigger across all the servers in
the cluster. Set to:
true to suspend document processing for the specied

trigger on all the servers in the cluster.

Note: To make the document processing change on all the

servers in a cluster, the Integration Server must belong to
a properly congured cluster and it must be congured to
synchronize trigger changes across the cluster. For more
information about conguring an Integration Server to
synchronize trigger management changes across a cluster,
see webMethods Integration Server Administrators Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

928

Odd Header
Trigger Folder

false to indicate that document processing for this trigger

should be suspended on the local Integration Server only.

This is the default.
The applyChangeAcrossCluster parameter applies only to
triggers that receive documents from the Broker.
Output Parameters
None.
Usage Notes
This service aects all documents in the specied trigger queue on the Integration
Server, including documents retrieved from the messaging provider and from local
publishing.

When you suspend document processing, the Integration Server will not dispatch any
more server threads to process documents in the trigger's queue. Any server threads
currently processing documents for the trigger will execute to completion. This includes
documents that are being retried.
When you suspend document processing, documents that the trigger retrieves will
collect in the trigger queue until the trigger resumes document processing. If the server
restarts before document processing resumes, volatile documents are discarded.
If you do not persist the change, the trigger reverts to the previously saved document
processing state when the server restarts, the trigger is enabled or disabled, or the
package containing the trigger reloads.
The Integration Server will not suspend document processing for the specied trigger
if the trigger is locked by a user. For more information about locking elements, see
webMethods Service Development Help.
If you suspend document processing, but do not suspend document retrieval for
a trigger, the trigger queue lls to capacity and Integration Server stops retrieving
documents for this trigger from the Broker.
If you set applyChangeAcrossCluster to true and the synchronization is not successful,
the following occurs:
If the Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases
(x of y updates failed). See server logs for more details.

webMethods Integration Server Built-In Services Reference Version 9.6

929

Even Header
Trigger Folder

If the Integration Server cannot update the Integration Servers in the cluster because
the change could not be made locally, the Integration Server Administrator displays
the following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors
are resolved.)

If the Integration Server cannot update the Integration Servers in the cluster because
cluster synchronization is not congured, the Integration Server writes the following
server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

You can use the Integration Server Administrator to view and change cluster
synchronization status for triggers. For more information, see webMethods Integration
Server Administrators Guide.
In a Java service, you can suspend document processing by calling
com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade.setProcessingSuspended().
For more information about this method, see the webMethods Integration Server Java API
Reference for the com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade class.
You can resume and suspend document processing for an individual trigger or
all triggers using the Integration Server Administrator. For more information, see
webMethods Integration Server Administrators Guide.
See Also
pub.trigger:resumeProcessing

pub.trigger:suspendRetrieval
WmPublic. Suspends retrieval of documents from the messaging provider for a specic
webMethods messaging trigger.
Input Parameters
triggerName

String Fully qualied name of the webMethods messaging

trigger for which you want to suspend document retrieval.

persistChange

String Optional. Flag indicating whether the document

retrieval change should be permanent or temporary. Set to:
true to save the change to le. Integration Server persists

the change across server restarts, package reloads, and

changes to trigger properties. The trigger will not retrieve
documents until retrieval is actively resumed via the
Integration Server Administrator or by execution of the
pub.trigger:resumeProcessing service.

webMethods Integration Server Built-In Services Reference Version 9.6

930

Odd Header
Trigger Folder

false to indicate that the change is temporary and will not

be maintained when the server restarts, the trigger is enabled

or disabled, or the package containing the trigger reloads.
This is the default.
applyChangeAcross
Cluster

String Optional. Flag indicating whether document retrieval

should be suspended for this trigger across all the servers in
the cluster. Set to:
true to suspend document retrieval for the specied trigger

on all the servers in the cluster.

Note: To make the document retrieval change on all the

servers in a cluster, the Integration Server be congured to
synchronize trigger changes across the cluster. For more
information about conguring an Integration Server to
synchronize trigger management changes across a cluster,
see webMethods Integration Server Administrators Guide.
false to indicate that document retrieval for this trigger

should be suspended on the local Integration Server only.

This is the default.
The applyChangeAcrossCluster parameter applies only to
triggers that receive documents from the Broker.
Output Parameters
None.
Usage Notes
This service does not aect document retrieval for locally published documents to which
the specied trigger subscribes.
When you suspend document retrieval, the specied trigger will continue to receive
documents delivered to the default client.
The Integration Server will not suspend document processing for the specied trigger
if the trigger is locked by a user. For more information about locking elements, see
webMethods Service Development Help.
When you suspend document retrieval, the Integration Server will not dispatch any
server threads to retrieve documents from the messaging provider for the trigger. Any
server threads currently retrieving documents for the trigger will execute to completion.
When you suspend document retrieval, documents to which this trigger subscribes will
collect in the trigger's client queue on the Broker. Documents remain in the trigger's
client queue until document retrieval resumes for the trigger or the documents expire.

webMethods Integration Server Built-In Services Reference Version 9.6

931

Even Header
Trigger Folder

If you do not resume document retrieval before the server restarts, the trigger package
reloads, or the trigger properties are modied, the Broker discards any volatile
documents in that trigger's client queue.
If you do not persist the change, the trigger reverts to the previously saved document
retrieval state when the server restarts, the trigger is enabled or disabled, or the package
containing the trigger reloads.
If you suspend document retrieval for a trigger, but do not suspend document
processing for the trigger, the trigger eventually processes all the documents that were
retrieved from the messaging provider for the trigger.
If you set applyChangeAcrossCluster to true and the synchronization is not successful, the
following occurs:
If the Integration Server does not update all the Integration Servers in the cluster
successfully, the Integration Server writes the following server log entry for each
server that could not be updated:
[ISS.0098.0107E] Error occurred during cluster invoke:
Alias = remoteAliasName ; Service = serviceName ; Exception = exceptionName

The Integration Server Administrator also displays the following message:

[ISS.0085.9203] Errors occurred while updating remote aliases (x of y
updates failed). See server logs for more details.

If the Integration Server cannot update the Integration Servers in the cluster because
the change could not be made locally, the Integration Server Administrator displays
the following message:
[ISS.0085.9204] Local update failed: Exception providing reason for failure.
(Note: The cluster synchronization will not run until all local errors
are resolved.)

If the Integration Server cannot update the Integration Servers in the cluster because
cluster synchronization is not congured, the Integration Server writes the following
server log entry:
[ISS.0033.0156W] Cluster invoke did not complete successfully.
Cluster Synchronization feature is not configured.

You can use the Integration Server Administrator to view and change cluster
synchronization status for triggers. For more information, see webMethods Integration
Server Administrators Guide.
In a Java service, you can suspend document retrieval by calling
setRetrievalSuspended(). For more information about this method,
see the webMethods Integration Server Java API Reference for the
com.wm.app.b2b.server.dispatcher.trigger.TriggerFacade class.
You can resume and suspend document retrieval for an individual trigger or all triggers
using the Integration Server Administrator. For more information, see webMethods
Integration Server Administrators Guide.
See Also
pub.trigger:resumeRetrieval
webMethods Integration Server Built-In Services Reference Version 9.6

932

Odd Header
TX Folder

37 TX Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

934

933

Even Header
TX Folder

Use services in the tx folder to perform administrative tasks for guaranteed delivery
transactions. For more information about guaranteed delivery, see the Guaranteed
Delivery Developers Guide and webMethods Integration Server Administrators Guide.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.tx:init

WmPublic. Initializes the processing of inbound

guaranteed delivery requests.

pub.tx:shutdown

WmPublic. Stops the processing of inbound

guaranteed delivery requests.

pub.tx:resetOutbound

WmPublic. Reinitializes the processing of outbound

guaranteed delivery requests.

pub.tx:init
WmPublic. Starts processing inbound guaranteed delivery requests. These are
guaranteed delivery transactions sent to Integration Server from client applications.
Input Parameters
None.
Output Parameters
Operation

String A message indicating whether the service completed

successfully. The service returns an exception if an error is
encountered.

Usage Notes
If you shut down the guaranteed delivery capabilities of Integration Server to correct
a conguration problem or to make an administrative change, use this service to
reinitialize guaranteed delivery.
You can also use this service to reinitialize guaranteed delivery if it becomes disabled
due to an error (for example, because of a disk full condition or if the job store database
becomes inaccessible). Reinitialize guaranteed delivery after you correct the problem.

webMethods Integration Server Built-In Services Reference Version 9.6

934

Odd Header
TX Folder

pub.tx:shutdown
WmPublic. Stops processing inbound guaranteed delivery requests. These are
guaranteed delivery transactions sent to Integration Server from client applications.
Input Parameters
None.
Output Parameters
Operation

String A message indicating whether the service completed

successfully. The service returns an exception if an error is
encountered.

Usage Notes
You might want to shut down guaranteed delivery to perform some administration
functions, such as correcting conguration errors or starting a new audit-trail log. (To
start a new audit-trail log, move or rename the existing log; the server automatically
starts a new log if one does not already exist.)

pub.tx:resetOutbound
WmPublic. Reinitializes the processing of outbound guaranteed delivery requests.
Outbound guaranteed delivery requests are those sent to another Integration Server.
Input Parameters
None.
Output Parameters
Operation

String A message indicating whether the service completed

successfully. The service returns an exception if an error is
encountered.

Usage Notes
If guaranteed delivery capabilities for outbound transactions become disabled due to
an error (for example, if the server encounters a disk full condition or if the job store
database becomes inaccessible), use this service to reinitialize guaranteed delivery after
you correct the problem. If you invoke this service while outbound guaranteed delivery

webMethods Integration Server Built-In Services Reference Version 9.6

935

Even Header
TX Folder

is functioning normally, the service will throw an exception and outbound guaranteed
delivery will not be reinitialized.

webMethods Integration Server Built-In Services Reference Version 9.6

936

Odd Header
UniversalName Folder

38 UniversalName Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

938

937

Even Header
UniversalName Folder

You use the elements in the universalName folder to list the contents of the Universal
Name Registry and to look up services or document types by their universal names.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.universalName:find

WmPublic. Returns the fully qualied service

name for an explicit universal name.

pub.universalName:findDocumentType

WmPublic. Returns the fully qualied

document type name for a provided explicit
universal name

pub.universalName:list

WmPublic. Returns a list of services in the

current universal-name registry.

pub.universalName:listAll

WmPublic. Returns the contents of the current

universal-name registry, including services and
document types.

pub.universalName:find
WmPublic. Returns the fully qualied service name for an explicit universal name.
Input Parameters
namespaceName

String Namespace portion of the universal name.

localName

String Local portion of the universal name.

Output Parameters
svcName

String Conditional. Fully qualied name of the service

associated with the universal name in namespaceName and
localName . If the specied universal name is not in the registry,
svcName will be null.

webMethods Integration Server Built-In Services Reference Version 9.6

938

Odd Header
UniversalName Folder

pub.universalName:findDocumentType
WmPublic. Returns the fully qualied document type name for a provided explicit
universal name
Input Parameters
namespaceName

String Namespace portion of the universal name.

localName

String Local name portion of the universal name.

Output Parameters
String Conditional. Fully qualied name of the document type
associated with the universal name in namespaceName and
localName . If the specied universal name is not in the registry,
svcName will be null.

svcName

pub.universalName:list
WmPublic. Returns a list of services in the current universal-name registry.
Input Parameters
None.
Output Parameters
names

Document List Service entries in the universal name registry. Each

document (IData object) in the list represents a service entry in the
universal-name registry. (There is one entry for every explicit universal
name that has been dened on the server. Implicit universal names are
not maintained in the registry.)
Each document in the list contains the following information:
Key

Description

universalName

Document The universal name associated with

the entry. This document contains the following
information:

webMethods Integration Server Built-In Services Reference Version 9.6

939

Even Header
UniversalName Folder

svcName

Key

Description

namespaceName

String Namespace portion of

the universal name.

localName

String Local portion of the

universal name.

String Fully qualied webMethods service

name associated with the entry (for example,
gl.post:postEntry).

Usage Notes
To return the entire contents of the universal-name registry, use the pub.universalName:listAll
service.

pub.universalName:listAll
WmPublic. Returns the contents of the current universal-name registry, including
services and document types.
Input Parameters
None.
Output Parameters
names

Document List Entries in the universal name registry. Each document

(IData object) in the list represents an entry in the universal-name
registry.
There is one entry for every explicit universal name that has been dened
on the server. Implicit universal names are not maintained in the registry.
Each document in the list contains the following information:
Key

Description

universalName

Document Universal name associated with the entry.

This document contains the following information:
Key

webMethods Integration Server Built-In Services Reference Version 9.6

Description

940

Odd Header
UniversalName Folder

svcName

namespaceName

String Namespace portion of

the universal name.

localName

String Local portion of the

universal name.

String Fully qualied Integration Server service

name or document type name associated with the
entry (for example, gl.post:postEntry).

Usage Notes
To return a list of the services in the universal-name registry only, use the
pub.universalName:listservice.

webMethods Integration Server Built-In Services Reference Version 9.6

941

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

942

Odd Header
Utils Folder

39 Utils Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

944

943

Even Header
Utils Folder

The utils folder contains utility services.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.utils:deepClone

WmPublic. Clones an object using the default

Java serialization mechanism.

pub.utils:executeOSCommand

WmPublic. Executes an operating system

command such as dir in Windows or ls in
UNIX.

pub.utils:generateUUID

WmPublic. Generates a random Universally

Unique Identier (UUID).

pub.utils:getServerProperty

WmPublic. Retrieves the value of a specied

server property.

pub.utils.ws:setCompatibilityModeFalse

WmPublic. Changes the value of the Pre-8.2

compatibility mode property for a web service
descriptor to false.

pub.utils:deepClone
WmPublic. Clones an object using the default Java serialization mechanism.
The originalObject and all its members must support the java.io.Serializable interface.
Input Parameters
originalObject

java.io.Serializable Object to be cloned.

Output Parameters
clonedObject

Object Copy of the originalObject .

webMethods Integration Server Built-In Services Reference Version 9.6

944

Odd Header
Utils Folder

pub.utils:executeOSCommand
WmPublic. Executes an operating system command such as dir in Windows or ls in
UNIX.
Caution: Use the pub.utils:executeOSCommand service with extreme caution; the commands
can aect the production systems where Integration Server is running.
Parameter Settings for OSCommands.cnf file
The OSCommands.cnf conguration le in the Integration Server_directory\instances
\instance_name \packages\WmPublic\cong directory contains parameters
that Integration Server uses to provide validation checks to make the
pub.utils:executeOSCommand service secure.
Note: If you make any changes to the OSCommands.cnf, you must reload the WmPublic
package or restart Integration Server for the changes to take eect.
For security reasons, the pub.utils:executeOSCommand service checks the input command
parameter against the list of allowedCommandsSpecied in the OSCommands.cnf
le. The service also checks the input workingDirectory parameter against the list of
allowedWorkingDirectories. If the input command or directory is not on the allowed list,
the service throws an exception.
Parameter Settings
The following table shows the parameter seings for the OSCommands.cnf le:
Parameter

Description

allowedOSCommands

List of commands that can be executed using the

pub.utils.executeOSCommand service.

allowedWorkingDirectories

List of directories where the allowed commands can be

executed.

When modifying the parameters in the OSCommands.cnf le, keep the following points
in mind:
Use semicolon (;) as the delimiter for the allowedOSCommands and
allowedWorkingDirectories parameters.
If a command name or working directory has a semicolon (;), use backslashes (\\)
before the semicolon while specifying the allowed paths.

webMethods Integration Server Built-In Services Reference Version 9.6

945

Even Header
Utils Folder

For example, if the allowed command is cmd.exe /c c:/temp/ab;c.txt, specify

it as cmd.exe /c c:/temp/ab\\;c.txt when specifying it as a parameter for the
OSCommands.cnf le.
Input Parameters
command

String Command to be executed on the target operating

system. You can include command parameters only if the
command parameters do not contain spaces.
Important: You must use arguments to specify all of the command
parameters if any one of the parameters contains spaces.

arguments

String List Optional. All of the command parameters for

the command . Add one element to the parameter for each
command parameter that you specify.

environment

String List Optional. An array of strings of environment

variable seings in the name=value format. Set the value to
null if you want the service to use the environment of the
current process as the environment for its subprocesses.

workingDirectory

String List Optional. The working directory from which the

command is to be executed. Set the value to null if you want
the service to use the working directory of the current process
as the working directory of its subprocesses.

Output Parameters
status

String The exit value of the executed command. The value 0

(zero) indicates normal termination.

outputMessage

String Output of the executed command.

errorMessage

String Errors that occurred during command execution.

Usage Notes
To execute the dir command on Windows XP using the pub.utils:executeOSCommand, the
command parameter is passed as cmd.exe /c dir and the working directory parameter
is passed as c:/temp. The outputMessage parameter will contain the les of c:/temp
directory.

webMethods Integration Server Built-In Services Reference Version 9.6

946

Odd Header
Utils Folder

pub.utils:generateUUID
WmPublic. Generates a random Universally Unique Identier (UUID).
Input Parameters
None.
Output Parameters
UUID

String A randomly generated Universally Unique Identier

(UUID).

pub.utils:getServerProperty
WmPublic. Retrieves the value of a specied server property.
Input Parameters
propertyName

String The name of the server property whose value you want
to retrieve (for example, wa.server.SOAP.directive).

defaultValue

String Optional. The default value to return if the server

property specied in propertyName does not exist. If the server
property does exist, the getServerProperty service ignores this
value.

Output Parameters
propertyValue

String The value of the requested server property. If the

property does not exist, and you did not set a defaultValue , the
getServerProperty service returns null.

pub.utils.ws:setCompatibilityModeFalse
WmPublic. Changes the value of the Pre-8.2 compatibility mode property for a web service
descriptor to false.

webMethods Integration Server Built-In Services Reference Version 9.6

947

Even Header
Utils Folder

Input Parameters
reportOnly

java.lang.Boolean Optional. Indicates whether the service actually

changes the Pre-8.2 compatibility mode property for the web service
descriptors and returns a summary of the changes or if the service
returns only a summary without making any changes. Set to:
true to return a summary of the web service descriptors that the

service would successfully and unsuccessfully change, including

the errors and warnings that would be encountered. The service
does not modify any web service descriptors.
false to change the Pre-8.2 compatibility mode property to false

for the specied web service descriptors, save the web service
descriptor, and return a summary of the changes. This is the
default.
convertAllPackages java.lang.Boolean Optional. Indicates whether the service changes
the Pre-8.2 compatibility mode property for web service descriptors
in all of the packages on Integration Server or only web service
descriptors in specic packages. Set to:
true to change the web service descriptors in all of the packages

on Integration Server.

When convertAllPackages is set to true, the

pub.utils.ws.setCompatibilityModeFalse service changes the Pre-8.2
compatibility mode property for those web service descriptors
in enabled packages only. Addionally, the service skips any
packages whose names begin with Wm.
false to change the web service descriptors in the packages

specied in packageNames only. This is the default.

Note: If you set convertAllPackages to false, you must specify

packages in packageNames .
packageNames

String List Optional. Names of the packages containing the web

service descriptors for which you want to change the Pre-8.2
compatibility mode property to false. The packages you specify must
be enabled. Note that package names are not case-sensitive.
Note: If you do not specify any packages in packageNames , you must
set convertAllPackages to true.

webMethods Integration Server Built-In Services Reference Version 9.6

948

Odd Header
Utils Folder

Output Parameters
updatedWarning
Count

String Conditional. Number of web service descriptors for which

changing the value of the Pre-8.2 compatibility mode property
to false resulted in a warning. If reportOnly is set to true,
updatedWarningCount indicates the number of web service
descriptors for which a warning would be generated. The
service returns updatedWarningCount only if Integration Server
encountered a warning when successfully changing the value of
the Pre-8.2 compatibility mode property from true to false for at least
one web service descriptor.
If the service did not (or would not if reportOnly is set to true)
update any web service descriptors, updatedWarningCount is not
returned.
Note: Some warnings require further action to be taken, such as
regenerating web service connectors. Be sure to review all warnings.

updated

Document List Conditional. The web service descriptors for

which the service successfully changed the value of the Pre-8.2
compatibility mode property from true to false, including any
warnings that occurred. If reportOnly is set to true, updated
indicates the number of web service descriptors that the service
would successfully change and any warnings that the service
would encounter.
The service returns the updated parameter only if the service
successfully changed the value of the Pre-8.2 compatibility mode
property from true to false for at least one web service descriptor.

failed

Key

Description

package

String Package that contains the updated web

service descriptor.

name

String Fully qualied name of the updated web

service descriptor.

warnings

String List List of any warning that occurred

when the service changed the Pre-8.2
compatibility mode property from true to false.

Document List Conditional. The web service descriptors for which

the service could not change the value of the Pre-8.2 compatibility
mode from true to false because an error occurred.

webMethods Integration Server Built-In Services Reference Version 9.6

949

Even Header
Utils Folder

The service returns the failed parameter only if an error prevented

the service from changing the value of the Pre-8.2 compatibility mode
property from true to false for at least one web service descriptor.

skipped

Key

Description

package

String Package containing the web service

descriptor that could not be changed.

name

String Fully qualied name of the web service

descriptor that could not be changed because of
an error.

warnings

String List List of the warnings that occurred

when the service aempted to change the
Pre-8.2 compatibility mode property from true to
false.

errors

String List List of the errors that prevented the

service from changing the value of the Pre-8.2
compatibility mode property from true to false.

Document List Conditional. The web service descriptors for which

the Pre-8.2 compatibility mode property is already set to false.
The service returns the skipped parameter only if the service
encountered web service descriptors for which Pre-8.2 compatibility
mode property was already set to false.
Key

Description

package

String Package containing the web service

descriptor.

name

String Fully qualied name of the web service

descriptors for which Pre-8.2 compatibility mode
property was already set to false.

Usage Notes
Even though the convertAllPackages and packageNames input parameters are optional,
you must either set convertAllPackages to true or specify packages in packageNames .
Use the pub.utils.ws:setCompatibilityModeFalse service to change the Pre-8.2 compatibility mode
property value for multiple web service descriptors at one time.

webMethods Integration Server Built-In Services Reference Version 9.6

950

Odd Header
Utils Folder

The Pre-8.2 compatibility mode property indicates the version of the web service stack with
which the web service descriptor is compatible:
When the Pre-8.2 compatibility mode property is set to true, the web service descriptor
runs on the earlier version of the web services stack, specically the web services
stack available in Integration Server versions 7.x, 8.0, and 8.0 SP1. web service
descriptors running in pre-8.2 compatibility mode have the same design-time
features and run-time behavior as web service descriptors run in versions of
Integration Server prior to version 8.2.
When the Pre-8.2 compatibility mode property is set to false, the web service descriptor
runs on the current version of the web services stack. web service descriptors that do
not run in pre-8.2 compatibility mode have the design-time features and run-time
behavior available in the current version of the web services stack.
For more details about which features are impacted by the compatibility mode of the
web service descriptor, see the Web Services Developers Guide.
Before changing the web service descriptor, the service veries that the web service
descriptor can be deployed to the web services stack that corresponds to the chosen
compatibility mode. Warnings indicate that the web service descriptor can be deployed
to the web services stack successfully but some run-time behavior might change.
If warnings occur for a particular web service descriptor, the service changes the
compatibility mode and lists warnings in the updated output parameter. Errors identify
the functionality that is incompatible with the web services stack. If errors occur for a
particular web service descriptor, the service does not change the compatibility mode
for that web service descriptor. the service identies the errors in the failed output
parameter.
Some warnings require further action to be taken, such as regenerating web service
connectors. Be sure to review all warnings.
The pub.utils.ws:setCompatibilityModeFalse service will not modify any web service descriptors
that are locked for edit or checked out at the time the service executes.
To use the pub.utils.ws:setCompatibilityModeFalse service to change the Pre-8.2 compatibility
mode property for a web service descriptor, you or whichever client is invoking the
service must have Write access to the web service descriptors.

webMethods Integration Server Built-In Services Reference Version 9.6

951

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

952

Odd Header
VCS Folder

40 VCS Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

954

953

Even Header
VCS Folder

You use the elements in the VCS folder to manage user associations for the Version
Control System Integration feature.
Note: You can also manage user associations between Designer and a VCS server from
the Solutions > VCS > User Mapping page in Integration Server Administrator. For more
information about the Version Control System Integration feature, see Conguring the
VCS Integration Feature.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.vcs.admin:getUsers

WmVCS. Returns a list of the Designer

user accounts that are associated with a
corresponding version control system (VCS)
user account on the VCS server.

pub.vcs.admin:removeCurrentUser

WmVCS. Removes the currently logged in

Designer user account from the list of users
associated with a version control system (VCS)
user account on the VCS server.

pub.vcs.admin:removeMultipleUsers

WmVCS. Removes the specied Designer user

accounts from the list of users associated with
a version control system (VCS) user account.

pub.vcs.admin:setCurrentUser

WmVCS. Associates a version control system

(VCS) user account with the currently logged
in Designer user account.

pub.vcs.admin:setMultipleUsers

WmVCS. Associates a version control system

(VCS) user account with the specied Designer
user accounts.

pub.vcs.admin:getUsers
WmVCS. Returns a list of the Designer user accounts that are associated with a
corresponding version control system (VCS) user account on the VCS server.

webMethods Integration Server Built-In Services Reference Version 9.6

954

Odd Header
VCS Folder

Input Parameters
None.
Output Parameters
users

Document List List of Designer user accounts with associations to a VCS

user account on the VCS server.
Key

Description

devName

String The name of the Designer user account.

vcsName

String The name of the VCS user account associated with

the devName account.

Usage Notes
This service is available only to administrator users.
This service is for use with the VCS Integration feature only.

pub.vcs.admin:removeCurrentUser
WmVCS. Removes the currently logged in Designer user account from the list of users
associated with a version control system (VCS) user account on the VCS server.
Input Parameters
None.
Output Parameters
None.
Usage Notes
This service is available to all users. After running this service, the currently logged in
Designer user account is no longer associated with a VCS user account. Nominally, this
prevents the Designer user from checking elements in to and out of the VCS repository.
However, on Windows operating systems, VCS actions will still be submied by
the VCS client with the user's current Windows user name. If the credentials of the
Windows user account match the credentials of a VCS account on the VCS server, the
VCS actions will be completed successfully.
This service is for use with the VCS Integration feature only.

webMethods Integration Server Built-In Services Reference Version 9.6

955

Even Header
VCS Folder

The user is advised to check in all checked out elements before running this service.
Version Control System Integration feature will not permit an element to be checked in
by other than the user who checked it out. This service has no eect on the VCS user
account.

pub.vcs.admin:removeMultipleUsers
WmVCS. Removes the specied Designer user accounts from the list of users associated
with a version control system (VCS) user account.
Input Parameters
devNames

String List The names of the Designer user accounts.

Output Parameters
None.
Usage Notes
This service is available only to administrator users. The user account name is casesensitive. After running this service, the Designer user accounts specied in the input
parameters are no longer associated with a VCS user account. Nominally, this prevents
the specied Designer users from checking elements in to and out of the VCS repository.
However, on Windows operating systems, VCS actions will still be submied by
the VCS client with the user's current Windows user name. If the credentials of the
Windows user account match the credentials of a VCS account on the VCS server, the
VCS actions will be completed successfully.
This service is for use with the VCS Integration feature only.
Administrators are advised to verify that all elements checked out by the specied
Designer users are checked in before running this service. The Version Control System
Integration feature feature will not permit an element to be checked in by other than the
user who checked it out. This service has no eect on the VCS user account.

pub.vcs.admin:setCurrentUser
WmVCS. Associates a version control system (VCS) user account with the currently
logged in the Designer user account. For information about restrictions on account
association, see the Usage Notes.
Input Parameters
vcsName

String The name of an existing VCS user account on the VCS server.

webMethods Integration Server Built-In Services Reference Version 9.6

956

Odd Header
VCS Folder

String The password of the VCS user account specied in vcsName .

vcsPassword

Output Parameters
None.
Usage Notes
This service is available to all users. A Developer user name does not have to be the
same as the associated VCS server user name, and all user account credentials are
case-sensitive. Each Designer user can have one VCS user account associated with the
Designer user account. Although it is possible for more than one Designer user to be
associated with the same VCS user account, Software AG recommends that you avoid
this conguration as it may result in errors or unpredictable results.
This service is for use with the VCS Integration feature only.
After running this service, the currently logged in Designer user account is associated
with a user account on the VCS server, enabling the Designer user to check
elements in to and out of the VCS repository (with proper ACL permissions). This
association is maintained until it is removed with the pub.vcs.admin:removeCurrentUser or
pub.vcs.admin:removeMultipleUsers services. This service does not validate, create, or modify
VCS server accounts.

pub.vcs.admin:setMultipleUsers
WmVCS. Associates a version control system (VCS) user account with the specied
Designer user accounts.
Input Parameters
devNames

Document List Information required to associate each Designer user

account with a VCS user account on the VCS server:
Key

Description

devName

String The name of the Designer user account.

vcsName

String The name of an existing VCS user account on the

VCS server.

vcsPassword

String The password of the VCS user account specied in

vcsName .

webMethods Integration Server Built-In Services Reference Version 9.6

957

Even Header
VCS Folder

Output Parameters
None.
Usage Notes
This service is available only to administrator users. A Designer user name does not
have to be the same as the associated VCS server user name, and the user account name
is case-sensitive. Each Designer user can have one VCS user account associated with the
Designer user account. Although it is possible for more than one Designer user to be
associated with the same VCS user account, Software AG recommends that you avoid
this conguration as it may result in errors or unpredictable results.
This service is for use with the VCS Integration feature only.
After running this service, the Designer user accounts specied in the input parameters
are associated with a corresponding user account on the VCS server, enabling the
Designer users to check elements in to and out of the VCS repository (with proper
ACL permissions). This association is maintained until it is removed with the
pub.vcs.admin:removeCurrentUser or pub.vcs.admin:removeMultipleUsers services. This service does
not validate, create, or modify VCS server accounts.

webMethods Integration Server Built-In Services Reference Version 9.6

958

Odd Header
XML Folder

41 XML Folder
Summary of Elements in this Folder .........................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

960

959

Even Header
XML Folder

You use the elements in the xml folder to perform operations on XML documents.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.xml:documentToXMLString

WmPublic. Converts a document (IData object)

to an XML string.

pub.xml:freeXMLNode

WmPublic. Frees the resources allocated to a

given XML node.

pub.xml:getNextXMLNode

WmPublic. Gets the next XML node from a

NodeIterator.

pub.xml:getXMLNodeIterator

WmPublic. Creates and returns a NodeIterator.

pub.xml:getXMLNodeType

WmPublic. Returns information about an XML

node.

pub.xml:loadEnhancedXMLNode

WmPublic. Retrieves an XML document

via HTTP or HTTPS, parses it using the
enhanced XML parser, and produces an
org.w3c.dom.Node object.

pub.xml:loadXMLNode

WmPublic. Retrieves an XML document via

HTTP or HTTPS, parses it using the legacy
XML parser, and produces an XML node.

pub.xml:queryXMLNode

WmPublic. Queries an XML node.

pub.xml:xmlNodeToDocument

WmPublic. Converts an XML node to a

document (an IData object).

pub.xml:xmlStringToEnhancedXMLNode

WmPublic. Converts an XML document

(represented as a String, byte[ ], or
InputStream) to an org.w3c.dom.Node object
using the enhanced XML parser.

pub.xml:xmlStringToXMLNode

WmPublic. Converts an XML document

(represented as a String, byte[ ], or

webMethods Integration Server Built-In Services Reference Version 9.6

960

Odd Header
XML Folder

Element

Package and Description

InputStream) to an XML node using the legacy
XML parser.

pub.xml:documentToXMLString
WmPublic. Converts a document (IData object) to an XML string.
This service recurses through a given document, building an XML representation from
the elements within it. Key names are turned into XML elements, and the key values are
turned into the contents of those elements.
This service would convert this document (IData object)...

To an XML document that looks like this...

<?xml version="1.0" ?>
<tns:AcctInfo>
xmlns:tns="http://localhost/DerivedAddress/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<name>Midwest Extreme Sports</name>

webMethods Integration Server Built-In Services Reference Version 9.6

961

Even Header
XML Folder

<rep>Laura M. Sanchez</rep>
<acctNum type=platinum>G97041A</acctNum>
<phoneNum cc=011>216-741-7566</phoneNum>
<address country=USA>
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
</address>
<address country=USA xsi:type="tns:DerivedAddress">
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
<landMark>Besides Ohio River-Bank Square</landMark>
<telNo>001222555</telNo>
</address>
<serialNum>19970523A</serialNum>
<serialNum>20001106G</serialNum>
<serialNum>20010404K</serialNum>
</tns:AcctInfo>

Note that:
Key names that start with the aribute prex (which, in this example, is the "@"
character) are turned into aributes of the elements in which they occur. For
example, the @type key in the acctNum element is converted to the type=platinum
aribute of the <acctNum> element in the resulting XML String.
Some modules, such as EDI and FlatFile, have elds that begin with the @ symbol
that will be considered aributes regardless of whether the arPrex is @ or another
character. For example, the FlatFile module always considers elds named @recordid and @delimiters to be aributes.
When a document type contains a String variable that represents a required aribute
(meaning that the variable name starts with the "@" symbol and the Required
property is set to True in Designer) and the input document does not contain the
required aribute, Integration Server adds an empty aribute during document
encoding. For example, if the document type contains a required String variable
named @myAribute but @myAribute is missing from the input document,
Integration Server adds myAttribute ="" to the XML document.
Note: Because empty xmlns aributes are invalid, if the document type contains a
required String variable named @xmlns and the input document does not specify a
value for the @xmlns aribute, Integration Serverdoes not add xmlns="" to the XML
document.
Also note that the *body key is used to represent the value of a simple element that
contains both a text value and an aribute. See the acctNum and phoneNum keys for
an example of this kind of element.
The *doctype eld is used to represent the IS document type to which the IData
object conforms. This eld is used to populate the relevant value for the xsi:type
aribute in the XML string. The document type referred by the *doctype eld
should either be created by importing an XSD le (XML schema) or generated while
consuming WSDL for a provider or consumer web service descriptor. You should

webMethods Integration Server Built-In Services Reference Version 9.6

962

Odd Header
XML Folder

also select the Register document types with schema type option in the New Document
Type wizard when generating a document type from an XML schema.
Fields that are not String or Document based (for example, Floats or Integers) are
converted to XML values using the underlying object's toString method.
Input Parameters
arPrex

String Optional. Prex that designates keys containing

aributes. The default prex is "@".
For example, if you set arPrex to ATT_ and document
contained the following element:

pub.xml:documentToXMLString would convert the ATT_currency

key to the aribute, currency=dollars, in the <tx> element
as shown below:
<tx currency=dollars>
<acct>cash</acct>
<amt>120.00</amt>
</tx>

document

Document IData object that is to be converted to XML. Note

that if you want to produce a valid XML document (one with
a single root node), document must contain only one top-level
IData object (that is, a single document). The name of that
document will serve as the name of the XML document's root
element.
For example, document shown in the example in this service's
description contains one top-level document named AcctInfo,
which would result in one root element named <AcctInfo> in
the resulting XML String.
If you needed to produce an XML fragment (for example, a
loose collection of elements that are not encompassed within
a single root element) then document can contain multiple toplevel elements. To produce this type of output, you must also
set the addHeader and enforceLegalXML parameters to false.

nsDecls

Document Optional. Namespaces associated with any

namespace prexes that are used in the key names in
document . Each entry in nsDecls represents a namespace
prex/URI pair, where a key name represents a prex and the
value of the key species the namespace URI.

webMethods Integration Server Built-In Services Reference Version 9.6

963

Even Header
XML Folder

For example, to dene the URIs associated with two prexes

called GSX and TxMon, you would set nsDecls as follows:

For each prex specied in nsDecls , pub.xml:documentToXMLString

generates an xmlns aribute and inserts it into the top-most
element of the resulting XML String. For example, if nsDecls
had the two keys shown above, pub.xml:documentToXMLString
would insert the following aributes into the root element of
the XML String:
xmlns:gsx="http://www.gsx.com"
xmlns:TxMon="http:www.acrtrak/txMonitor"

Note: Alternatively, you can declare a namespace by including an

@xmlns key in document . (If you were not using the @ character
to designate aributes, use the correct aribute prex in your
code.)
addHeader

String Optional. Flag specifying whether the header element:

<?xml version="1.0"?>

is to be included in the resulting XML String.

Set to:
true to include the header. This is the default.
false to omit the header. (You would omit the header to

generate an XML fragment or to insert a custom header.)

encode

String Optional. Flag indicating whether to HTML-encode the

data. Set this parameter to true if your XML data contains
special characters, including the following: < > & " '
Set to:
true to HTML-encode the data.

For example, the string expression 5 < 6 would be converted

to <expr>5 &lt; 6</expr>, which is valid.
false to not HTML-encode the data. This is the default.

For example, the string expression 5 < 6would be converted

to <expr>5 < 6</expr>, which is invalid.
documentTypeName

String Optional. Fully qualied name of the document

type that describes the structure and format of the output
document (for example, examples.rtd:exampleRecord1).

webMethods Integration Server Built-In Services Reference Version 9.6

964

Odd Header
XML Folder

You can use this parameter to ensure that the output includes
elements that might not be present in document at run time, or
to describe the order in which elements are to appear in the
resulting XML String.
generateRequiredTags String Optional. Flag indicating whether empty tags are to
be included in the output document if a mandatory element
appears in the document type specied in documentTypeName
but does not appear in document . Set to:
true to include mandatory elements if they are not present in

document.

false to omit mandatory elements if they are not present in

document . This is the default.

Note: The generateRequiredTags is only applicable if

documentTypeName is provided.
generateNilTags

String Optional. Flag indicating whether the resulting XML

string includes the aribute xsi:nil for elements that are null.
Set to:
true to generate the xsi:nil aribute for an element if the

Allow null property for the corresponding eld is set to true

and the eld is null in document .
Note: generateRequiredTags must also be set to true to
generate the xsi:nil aribute in the XML String.

false to omit the xsi:nil aribute even if a nillable eld is, in

fact, null. This is the default.

enforceLegalXML

String Optional. Flag indicating whether the service throws an

exception when document contains multiple root elements or
illegal XML tag names. Set to:
true to throw an exception if document would produce an

XML String containing multiple root elements and/or illegal

XML tag names.
false to allow the resulting XML String to contain multiple

root elements and/or illegal XML tag names. You would

use this seing, for example, to create an XML fragment
composed of multiple elements that were not all enclosed
within a root element. This is the default.
dtdHeaderInfo

Document Optional. Contents of the DOCTYPE header

to be inserted into the XML String. (You can retrieve

webMethods Integration Server Built-In Services Reference Version 9.6

965

Even Header
XML Folder

this information from an incoming document using

pub.xml:getXMLNodeType.)

buerSize

Key

Description

systemID

String Optional. System identier for the

DTD, if any.

publicID

String Optional. Public identier for the

DTD, if any.

rootNSPrex

String Optional. Namespace prex of the

rootLocalName , if any.

rootLocalName

String Optional. Local name (excluding

the namespace prex) of the root
element.

String Optional. Initial size (in bytes) of the String buer that
documentToXMLString uses to assemble the output XML String. If
the String buer lls up before documentToXMLString is nished
generating the XML String, it reallocates the buer, expanding
it by this amount each time the buer becomes full.
If you do not set buerSize , documentToXMLString looks to see
whether a default buer size is specied in the following
parameter on the server:
wa.server.recordToDocument.buerSize
If so, it uses this value to allocate the String buer. If this
parameter is not set, documentToXMLString uses a default buer
size of 4096 bytes.
For best performance, you should always set buerSize to a
value that closely matches the size of the XML String that you
expect documentToXMLString to produce. This practice will spare
the server from having to enlarge the buer repeatedly if the
XML String is many times larger than the default buer or if
you arbitrarily set buerSize to a value that is too small.
Seing buerSize to an appropriately sized value will also
prevent your service from unnecessarily consuming more
memory than it needs if the XML String is much smaller than
the default buer size or if you arbitrarily set buerSize to a
value that is too large.

webMethods Integration Server Built-In Services Reference Version 9.6

966

Odd Header
XML Folder

Output Parameters
xmldata

String XML String produced from document .

Usage Notes
If you are building an IData that will be converted to an XML String, keep the following
points in mind:
If you want to generate a simple element that contains only a character value,
represent it with a String element in document as shown in the following:

If you want to generate an element that contains children, represent with an IData in
document as shown in the following.

To produce aributes, put the aribute values in keys whose name starts with the
character(s) specied in arPrex . For example, if you use the default arPrex , the
names of all keys containing aributes (and only those keys containing aributes) must
start with the @ character (for example, @type, @xmlns).
Also, when you include aributes, make sure that keys representing aributes are direct
children of the elements in which they are to be applied. For example, if you want to
include an xmlns aribute in the <AcctInfo> element in the example shown in the
description of this service, you must create a String eld named @xmlns in the AcctInfo
eld within document .
If you want to generate a simple element that contains a character value and one or
more aributes, you must represent it as an IData that has one key for each aribute
and a key named *body that contains element's value. For example, if you wanted to
produce the following element:
<phoneNum cc=011>216-741-7566</phoneNum>

You would include the following in document :

To include namespaces, make sure you do the following:

webMethods Integration Server Built-In Services Reference Version 9.6

967

Even Header
XML Folder

Include the appropriate namespace prex in the key names in document . For
example, to produce an element called acctNum that belongs to a namespace
that is represented by the "GSX" prex, you would include a key named
GSX:acctNum in document .
Dene the URIs for the prexes that appear in document . You can do this through
nsDecls or by including an @xmlns key in the element where you want the xmlns
aribute to be inserted. See the nsDecls description above for more information
about declaring namespaces.
To return the processed XML document to the client that originally submied it, invoke
pub.flow:setResponse. Keep in mind that you may need to modify the encoding.
To generate the xsi:nil aribute for an element in the XML String, the following must be
true:
documentTypeName must be provided.
generateRequiredTags and generateNilTags must be set to true.
The element must correspond to a eld that is nillable. That is, the Allow null property
must be set to True.
If the element corresponds to a document eld, at run time, the document must
not contain any content. However, if the document contains a *body eld, the
pub.xml:documentToXMLString service generates the xsi:nil aribute for the corresponding
element if the value of *body is null.
If a document eld is nillable and is null at run time, the resulting XML String does not
contain any child elements for the element that corresponds to the document.
By default, the pub.xml:documentToXMLString service uses the prex "xsi" for the nil aribute,
where xsi refers to the namespace hp://www.w3.org/2001/XMLSchema-instance.
If nsDecls declares a dierent prex for this namespaces, the service uses that prex
instead of xsi.

pub.xml:freeXMLNode
WmPublic. Frees the resources allocated to a given XML node.
You can optionally call this service when you are using a NodeIterator to iterate over
an XML node and you decide to stop processing the node before reaching the end. By
explicitly calling pub.xml:freeXMLNode, you immediately free the resources associated
with the node instead of waiting for Java garbage collection to do this. Although it is
not mandatory to call this service when you nish processing an XML node with a
NodeIterator, doing so can boost server performance. Note that after you have freed an
XML node using this service, the node becomes unstable and should not be used by any
subsequent processes.

webMethods Integration Server Built-In Services Reference Version 9.6

968

Odd Header
XML Folder

Input Parameters
rootNode

XML node or enhanced XML node whose resources you want

to release. This parameter supports the following types of
input:
com.wm.lang.xml.Document An XML node whose resources you
want to release.
enhanced XML node An enhanced XML node whose resources
you want to release.
Specify the same type of input that you supplied to
pub.xml:getXMLNodeIterator.

Output Parameters
None.

pub.xml:getNextXMLNode
WmPublic. Gets the next XML node from a NodeIterator.
Input Parameters
iterator

com.wm.app.b2b.util.NodeIterator NodeIterator from which to

retrieve the next node.

Output Parameters
next

Document Conditional. The requested node. Will be null when

the NodeIterator has no more nodes to return. Otherwise, next
will contain the following:
Key

Description

name

String Element type name of the node.

If the element belongs to a namespace
and the namespace was declared at the
time the NodeIterator was constructed,
name will have the prex declared for
that namespace. If the namespace is
not declared, name will use prex that
occurs in the XML.

webMethods Integration Server Built-In Services Reference Version 9.6

969

Even Header
XML Folder

node

XML node identied by the input

criteria used to originally generate
the NodeIterator. node will be
one of the following types and
depends on what was supplied to
the node input parameter for the
pub.xml:getXMLNodeIterator: service:
com.wm.lang.xml.Node
enhanced XML node

It is possible that all calls to getNextXMLNode on a given

NodeIterator will yield the same document instance, where
the values of the instance's entries vary. For this reason,
applications should assume that each call to getNextXMLNode
invalidates the document returned by the previous call. This
approach maximizes the speed of the server and minimizes
the use of resources.
Usage Notes
A NodeIterator is acquired via the service pub.xml:getXMLNodeIterator. The output of that
service is a document (IData object) containing the element type name of the node and
the node itself. The instance of this document is only valid until the next getNextXMLNode
call on the same NodeIterator, because getNextXMLNode uses the same document object for
each call.

pub.xml:getXMLNodeIterator
WmPublic. Creates and returns a NodeIterator.
A NodeIterator iterates over the element node descendants of an XML node and returns
the element nodes that satisfy the given criteria. The client application or ow service
uses the service pub.xml:getNextXMLNode to get each node in turn. NodeIterators can only
be created for XML nodes (not for HTML nodes).
getXMLNodeIterator is useful for loading and parsing documents on demand. Large or slow
documents need only be loaded as far as needed to get the desired data. NodeIterators
are also useful for providing service as the pertinent information in the document
arrives rather than rst waiting for the entire document to load. This service is primarily
intended to deal with large documents or documents that arrive slowly.
NodeIterator provides a moving-window mode, in which the only node that is resident
in memory is the last node returned by pub.xml:getNextXMLNode. In this mode, when
pub.xml:getNextXMLNode is called, all nodes preceding the newly returned node become
invalid, including all nodes previously returned by pub.xml:getNextXMLNode. The client
must fully complete processing preceding nodes before advancing the window by

webMethods Integration Server Built-In Services Reference Version 9.6

970

Odd Header
XML Folder

calling pub.xml:getNextXMLNode again. In moving-window mode, the document consumes

at least enough memory to hold the most recently returned node.
Moving-window mode allows the server to process multi-megabyte XML documents
using very lile memory. Moving-window mode may only be used on a node that
represents an entire XML document and not on any descendant node.
Note: You can use moving-window mode if the input node is of type
com.wm.lang.xml.Node only. Moving-window mode cannot be used with an enhanced
XML node.
Input Parameters
node

The XML node or enhanced XML node for which you want
to produce a NodeIterator. This parameter supports the
following types of input:
com.wm.lang.xml.Node XML node for which you want to
produce a NodeIterator. The node can represent either
an XML document or an element of an XML document;
however, if the NodeIterator will be used in moving-window
mode, a whole XML document must be used. This is because
moving window mode is only meaningful for managing the
loading process of a document, and to operate on a node is to
have already loaded the node
enhanced XML node An enhanced XML node for which
you want to produce a NodeIterator. An enhanced XML
node can be produced by pub.xml:loadEnhancedXMLNode,
pub.xml:xmlStringToEnhancedXMLNode, or a content handler that
receives an XML document in a request for which xmlFormat
is set to enhanced.

criteria

String List Optional. Paern strings identifying the nodes that

the iterator is to return. A paern string may take either the
form <localName> or the form <prefix>:<localName>.
When a paern takes the rst form, it identies an element
whose local name is <localName> and that belongs to
the default XML namespace. When a paern takes the
second form, it identies an element whose local name is
<localName> and whose XML namespace is given by the
prex <prefix>. If the input parameter nsDecls declares this
prex, the namespace URI of the element must match the URI
declared for the prex. If the prex is not declared in nsDecls ,
the prex is matched against prexes found in the XML.
<prefix> and <localName> can each optionally take the
value "*" (asterisk) to match any namespace or local name.

webMethods Integration Server Built-In Services Reference Version 9.6

971

Even Header
XML Folder

A "*" prex also matches elements residing in the default

namespace.
If you do not specify criteria , all element node children of the
root element are returned.
nsDecls

Document Optional. Namespaces associated with any

namespace prexes used in criteria . Each entry in nsDecls
represents a namespace prex/URI pair, where a key name
represents a prex and the value of the key species the
namespace URI.
For example, to dene the URIs associated with two prexes
called GSX and TxMon, you would set nsDecls as follows:

movingWindow

String Optional. Flag indicating whether the NodeIterator

is to iterate using a moving window, as described above. In
moving-window mode, the entire document preceding the
node most recently returned by getXMLNodeIterator is discarded.
Subsequent aempts to return preceding portions of the
document will return either the repeating text *PURGED* or the
proper data, depending on whether the data falls within an
area that the server was able to discard. When iterating with
a moving window, the current node should be queried and
completely examined prior to requesting the next node.
Set to:
true to use the NodeIterator in moving-window mode.
false to use the NodeIterator in normal mode. This is the

default.

Note: If node is an enhanced XML node, set movingWindow to

false.
Output Parameters
iterator

com.wm.app.b2b.util.NodeIterator NodeIterator for use with the

service pub.xml:getNextXMLNode.

webMethods Integration Server Built-In Services Reference Version 9.6

972

Odd Header
XML Folder

pub.xml:getXMLNodeType
WmPublic. Returns information about an XML node.
Input Parameters
rootNode

com.wm.lang.xml.Document XML node about which you want

information.

Output Parameters
systemID

String Conditional. System identier, as provided by the DTD

associated with rootNode . If rootNode does not have a system
identier, this value is null.

publicID

String Conditional. Public identier, as provided by the DTD

associated with rootNode . If rootNode does not have a public
identier, this value is null.

rootNamespace

String URI of the XML namespace to which rootNode's root

element belongs.

rootNSPrex

String Conditional. Namespace prex of root element in

rootNode , if any.

rootLocalName

String Conditional. Local name (excluding the namespace

prex) of the root element in rootNode , if any.

pub.xml:loadEnhancedXMLNode
WmPublic. Retrieves an XML document via HTTP or HTTPS, parses it using the
enhanced XML parser, and produces an org.w3c.dom.Node object.
An DOM node is a special representation of an XML document that can be consumed
by any program that uses standard DOM APIs. The pub.xml:xmlNodeToDocument service can
accept a DOM object as input.
Input Parameters
url

String The URL of the document you want to load. This string
must begin with http: or https:. For example:

webMethods Integration Server Built-In Services Reference Version 9.6

973

Even Header
XML Folder

http://www.rubicon.com/orders/orders.html

OR
https://localhost:5555/WmPublic/index.html

You can include a query string (for example, a collection of

"name=value" pairs) with the string that you specify. However,
you might want to use the data variable for this type of
information instead. It is usually a more practical place for
"name=value" data, because it allows you to link individual
variables in the query string.
method

String Optional. Set this value to specify the HTTP method

(GET or POST) that you want the target server to execute on
the resource specied in url . This value determines the way in
which pub.xml:loadEnhancedXMLNode submits data values (if any)
to the resource identied in url .
If you set method to get, pub.xml:loadEnhancedXMLNode
appends the values you specify in data to the value in url .
(Note that only certain data elements are valid when you use
the GET method). The default is get.
If you set method to post, pub.xml:loadEnhancedXMLNode sends
the values in data in the body of the HTTP or HTTPS request.

auth

Document Optional. Authentication and authorization

information that pub.xml:loadEnhancedXMLNode will use if the
requested resource is protected.
Note: If you include your data with the string in url , do not
specify a value in data .
Key

Description

type

String Type of authentication

pub.xml:loadEnhancedXMLNode will use
to submit this request. Leave this eld
blank, as the only option currently
available is basic HTTP authentication.

user

String User name that

pub.xml:loadEnhancedXMLNode will submit
if the requested resource is protected.
The user name must have authority to
access the resource specied in url .

webMethods Integration Server Built-In Services Reference Version 9.6

974

Odd Header
XML Folder

This value defaults to the value of

wa.net.hpUser in the server's
conguration le (server.cnf).
pass

String Password associated with the

user name specied in user . If the user
does not require a password, leave pass
empty.
This value defaults to the value of
wa.net.hpPass in the server's
conguration le (server.cf).

data

Document Optional. The data that you want

pub.xml:loadEnhancedXMLNode to submit with the request. Specify
data using one or more of the following elements.
Note: When you use more than one element to submit data,
args is appended rst, table is appended second, and string is
appended last.
Key

Description

args

Document Optional. Species

name=value pairs that
pub.xml:loadEnhancedXMLNode is to submit
to the resource in url .
You can use args to submit data via
either the POST or GET method.
To specify data using args , create one
element for each name=value pair that
you want to submit, where the key
represents the name portion of the
pair and the value represents the value
portion of the pair.
Note that when you use args ,
pub.xml:loadEnhancedXMLNode will
automatically:
URL-encode name=value pair, so you
do not need to URL-encode the values
you specify in args .
Insert the "&" character between pairs,
so you do not need to include it in
args .

webMethods Integration Server Built-In Services Reference Version 9.6

975

Even Header
XML Folder

Prex the entire query string with the

"?" character if it submits the data in
args via a GET. You do not need to
include this character in args .
When you submit data using the
args variable, Integration Server
automatically sets the value of the
Content-Type header to application/
x-www-form-urlencoded. If you want
to explicitly specify a dierent ContentType, you must submit your data using
the string or bytes variable.
table

String Table Optional. Species data that

pub.xml:loadEnhancedXMLNode will use to
construct a query string to submit to the
resource specied in url .
table is similar to args , but it allows you
to submit unnamed values in a query
string, not just name=value pairs.
To specify data using table , create one
row for each value that you want to
submit, where:
The contents of column 0 represent the
name portion of the pair (leave this
column null to submit an unnamed
value, and...
The contents of column 1 represent the
value portion of the pair.
When you submit data using the
table variable, the Integration Server
automatically sets the value of the
Content-Type header to application/
x-www-form-urlencoded. If you want
to explicitly specify a dierent ContentType, you must submit your data using
the string or bytes variable.
Note that when you use table ,
pub.xml:loadEnhancedXMLNode will
automatically:
URL-encode name=value pair, so you
do not need to URL-encode the values
you specify in table .

webMethods Integration Server Built-In Services Reference Version 9.6

976

Odd Header
XML Folder

Insert the "&" character between the

pairs (or unnamed values) that it
constructs, so you do not need to
include it in table .
Prex the entire query string with the
"?" character if it submits the data in
table via the GET method. You do not
need to include this character in table .
string

String Optional. Text that you want

pub.xml:loadEnhancedXMLNode to submit to
the resource in url .
You can use string to submit data via
either the POST or GET method.
If you use string to specify your data,
make sure that you specify the string
exactly as you want it presented in the
HTTP request. (If you are using the GET
method, make sure you URL-encode the
contents of string ). When performing
a POST the string is submied to the
resource as the body of the document.

bytes

byte[ ] Optional. Data that

pub.xml:loadEnhancedXMLNode is to submit
to the resource in url . You can use
bytes only to submit data via the POST
method.
Note: When you use bytes and another
element (args , table , or string ) to submit
data with pub.xml:loadEnhancedXMLNode, the
service appends the data from the args ,
table , or string element to url . The service
appends args to url rst, table second, and
string last. The service encodes the data
from the bytes element in the body of the
post.

stream

java.io.InputStream Optional. Data that

pub.xml:loadEnhancedXMLNode is to submit
to the resource in url . You can use
stream only to submit data via the POST
method.

webMethods Integration Server Built-In Services Reference Version 9.6

977

Even Header
XML Folder

Note: When you use stream and another

element (args , table , or string ) to submit
data with pub.xml:loadEnhancedXMLNode, the
service appends the data from the args ,
table , or string element to url . The service
appends args to url rst, table second,
and string last. The service encodes the
data from the stream element in the body
of the post. If stream is specied, bytes is
ignored.
encoding
headers

String Optional. Name of a registered

IANA character set.

Document Optional. Fields that you want to explicitly

override in the HTTP request header issued by
pub.xml:loadEnhancedXMLNode.
Specify one element for each header eld that you want to set,
where the element's name represents the name of the header
eld, and the element's value represents the value of that
header eld.
If headers is not set, pub.xml:loadEnhancedXMLNode will use its
default header values.
Note: You do not need to type a colon after the eld name
because pub.xml:loadEnhancedXMLNode will automatically insert the
colon when it inserts this eld into the request header.
If you want to assign specic values to header elds used by
pub.xml:loadEnhancedXMLNode, keep the following points in mind:
When you specify the value of a header eld, you override
whatever default value webMethods Integration Server
is congured to use for HTTP requests. For example, if
you set the User-Agent header eld to B2B/3.0, the server
uses that value instead of the default value specied by the
wa.net.userAgent parameter.
The pub.xml:loadEnhancedXMLNode service automatically
determines the value of the Content-Length header eld. You
cannot specify a value for Content-Length.
Be aware that when you submit data using the args or table
elements, pub.xml:loadEnhancedXMLNode automatically sets
the Content-Type header eld to application/x-wwwformurlencoded. You cannot override this seing using the
headers variable. If you want to explicitly specify a content

webMethods Integration Server Built-In Services Reference Version 9.6

978

Odd Header
XML Folder

type in headers, make sure to use the string or bytes element

to submit your data, not args or table .
Certain header elds are automatically derived
from other input parameters assigned to
pub.xml:loadEnhancedXMLNode. For example, the
Authorization header eld is automatically derived from
your auth parameter seing. Except for the Content-Length
header eld and the Content-Type header eld (which, as
described above, you cannot override when submiing
data via args or table ), a value that you specify in headers
overrides the value that pub.xml:loadEnhancedXMLNode
might otherwise derive from other parameter seings.
The pub.xml:loadEnhancedXMLNode service does not validate data
that you specify in headers . It simply passes it on to the target
server in the request header. Make sure you specify header eld
names and their values correctly. For a complete list of valid
request header elds, see hp://www.w3.org for the latest
HTTP specication published by the W3C.
To specify request headers in headers , create a string element
for each header that you want to specify, where:
The name of the element denes the name header
eld (for example, User-Agent, If- Modied-Since,
Mail_Address), and
The value of the element species the value you want
assigned to that eld.
encoding

String Optional. Character set in which the returned document

is encoded. The parser requires this value in order to interpret
a document correctly. Set to:
autoDetect to determine the document's character set from

the document, where UTF-8 is the default character set for

XML.
The name of a registered IANA character set to decode
the document using that character set (for example,
ISO-8859-1).
failOnHTTPError

String Optional. Determines whether

pub.xml:loadEnhancedXMLNode will fail (throw an exception) if
the requested URL is not loaded correctly based on an HTTP
status code. This parameter allows for customized error
handling of the load failure. Set to:

webMethods Integration Server Built-In Services Reference Version 9.6

979

Even Header
XML Folder

true to throw a service exception if the URL is not loaded

as indicated by an HTTP status code between 400 and 599,

inclusive.
false to ignore HTTP errors. If there is an error,

pub.xml:loadEnhancedXMLNode returns status and statusMessage .

This is the default.
inputProcessing

Document. Optional. Contains a set of input parameters

that instruct Integration Server how to read the XML
document. The elds are comparable to those in the
javax.xml.stream.XMLInputFactory class.
Key

Description

isValidating

String Optional. Determines whether

Integration Server performs DTD
validation. Set to:
true to perform DTD validation.
false to disable DTD validation. This

is the default.
isNamespaceAware

String Optional. Determines whether

Integration Server provides namespace
processing for XML 1.0 support while
parsing the XML document. Set to:
true to enable namespace processing.

This is the default.

false to disable namespace

processing.
isCoalescing

String Optional. Determines whether

Integration Server coalesces adjacent
character data while parsing the XML
document. Set to:
true to coalesce adjacent character

data.

false to indicate that Integration

Server does not coalesce adjacent

character data. This is the default.
isReplacingEntity
References

String Optional. Determines whether,

while parsing the XML document,
Integration Server replaces internal

webMethods Integration Server Built-In Services Reference Version 9.6

980

Odd Header
XML Folder

entity references with replacement text

and treats them as characters. Set to:
true to replace entity references. This

is the default.

false to indicate entity references will

not be replaced.
isSupporting
ExternalEntities

String Optional. Determines whether

Integration Server resolves external
parsed entities while parsing the XML
document. Set to:
true to resolve external parsed

entities.

false to indicate Integration Server

does not resolve external parsed

entities.

The JVM in which Integration Server

runs determines the default.
supportDTD

String Optional. Determines whether

Integration Server supports DTDs while
parsing the XML document. Set to:
true to support DTDs while parsing

the XML document. This is the default.

false to disable support of DTDs

while parsing the XML document.

partitionSize

String Optional. Species the size, measured in bytes, of the

partitions on the heap where the enhanced XML parser stores
parsed document information. Specify a sux of k to
indicate kilobytes or m to indicate megabytes. For example,
10k or 10m.
If you do not specify a value, Integration Server uses the
default partition size value specied on the Settings > Enhanced
XML Parsing screen in Integration Server Administrator.

Output Parameters
node

org.w3c.dom.Node Conditional. XML node representing the

returned ML document.

webMethods Integration Server Built-In Services Reference Version 9.6

981

Even Header
XML Folder

The pub.xml:loadEnhancedXMLNode service returns node

only when Integration Server parses the XML document
successfully.
String Conditional. The HTTP status code returned by the
target server if an HTTP error occurs when loading the
requested URL.

status

The pub.xml:loadEnhancedXMLNode service returns status when an

HTTP error occurs and failOnHTTPError is set to false.
statusMessage

String Conditional. The HTTP status message returned by

the target server if an HTTP error occurs when loading the
requested URL.
The pub.xml:loadEnhancedXMLNode service returns statusMessage
when an HTTP error occurs and failOnHTTPError is set to
false.

Usage Notes
If pub.xml:loadEnhancedXMLNode does not receive a response within the timeout period
specied in the server's wa.net.timeout parameter, it will throw an exception. For
information about the wa.net.timeout parameter, see webMethods Integration Server
Administrators Guide.
Use the pub.xml:loadXMLNode service to load an XML document and convert it to an XML
node using the legacy XML parser. For more information about the legacy XML parser
and the enhanced XML parser, see webMethods Integration Server Administrators Guide.
Keep the following information in mind when specifying a partitionSize
The partitionSize is a hint for the enhanced XML parser so that it can estimate the
amount of heap space needed to parse the document. Often, it not possible to
determine the size of an inbound XML document before parsing.
As a general rule, Software AG recommends a partitionSize that is 1/2 the size of the
unparsed XML document.
A partitionSize that is considerably larger than 1/2 the size of the unparsed XML
document causes the enhanced XML parser to consume more heap space than
necessary but might also improve throughput. However, this can impact the
overall performance of Integration Server.
A partitionSize that is considerably smaller than 1/2 the size of the unparsed XML
document causes the enhanced XML parser to create a large number of partitions
to parse the document. While this might use less heap space, it may reduce the
throughput of the parser.
A partitionSize that is three times smaller or three times larger than 1/2 the size of
the unparsed XML document will likely have lile impact on the performance.

webMethods Integration Server Built-In Services Reference Version 9.6

982

Odd Header
XML Folder

At run time, the enhanced XML parser overrides a partitionSize that consumes all of
the available heap space.
At run time, if the partitionSize results in an initial heap allocation that exceeds
the single document limit set in the Maximum heap allocation for any single document
eld the limit for all documents set in the Maximum heap allocation for all documents
combined eld, the enhanced XML parser reduces the partition size automatically.
For more information about heap allocation limits for the enhanced XML parser, see
webMethods Integration Server Administrators Guide
If you do not specify partitionSize , the enhanced XML parser uses the default
specied in the Default partition size eld on the Settings > Enhanced XML Parsing page in
Integration Server Administrator.

pub.xml:loadXMLNode
WmPublic. Retrieves an XML document via HTTP or HTTPS, parses it using the legacy
XML parser, and produces an XML node.
An XML node is a special representation of an XML document that can be consumed
by the Integration Server. Most webMethods services that operate on XML documents
require an XML node as input.
Input Parameters
url

String The URL of the document you want to load. This string
must begin with http: or https:. For example:
http://www.rubicon.com/orders/orders.html

OR
https://localhost:5555/WmPublic/index.html

You can include a query string (for example, a collection of

"name=value" pairs) with the string that you specify. However,
you might want to use the data variable for this type of
information instead. It is usually a more practical place for
"name=value" data, because it allows you to link individual
variables in the query string.
method

String Optional. Set this value to specify the HTTP method

(GET or POST) that you want the target server to execute on the
resource specied in url . This value determines the way in
which pub.xml:loadXMLNode submits data values (if any) to the
resource identied in url . The default is get.
If you set method to get, pub.xml:loadXMLNode appends the
values you specify in data to the value in url . (Note that

webMethods Integration Server Built-In Services Reference Version 9.6

983

Even Header
XML Folder

only certain data elements are valid when you use the GET
method).
If you set method to post, pub.xml:loadXMLNode sends the
values in data in the body of the HTTP or HTTPS request.
auth

Document Optional. Authentication and authorization

information that pub.xml:loadXMLNode will use if the requested
resource is protected.
Note: If you include your data with the string in url , do not
specify a value in data .
Key

Description

type

String Type of authentication

pub.xml:loadXMLNode will use to submit
this request. Leave this eld blank, as
the only option currently available is
basic HTTP authentication.

user

String User name that pub.xml:loadXMLNode

will submit if the requested resource is
protected.
The user name must have authority to
access the resource specied in url .
This value defaults to the value of
wa.net.hpUser in the server's
conguration le (server.cnf).

pass

String Password associated with the

user name specied in user . If the user
does not require a password, leave pass
empty.
This value defaults to the value of
wa.net.hpPass in the server's
conguration le (server.cf).

data

Document Optional. The data that you want pub.xml:loadXMLNode

to submit with the request. Specify data using one or more of
the following elements.
Note: When you use more than one element to submit data,
args is appended rst, table is appended second, and string is
appended last.

webMethods Integration Server Built-In Services Reference Version 9.6

984

Odd Header
XML Folder

Key

Description

args

Document Optional. Species

name=value pairs that
pub.xml:loadXMLNode is to submit to the
resource in url .
You can use args to submit data via
either the POST or GET method.
To specify data using args , create one
element for each name=value pair that
you want to submit, where the key
represents the name portion of the
pair and the value represents the value
portion of the pair.
Note that when you use args ,
pub.xml:loadXMLNode will automatically:
URL-encode name=value pair, so you
do not need to URL-encode the values
you specify in args .
Insert the "&" character between pairs,
so you do not need to include it in
args .
Prex the entire query string with the
"?" character if it submits the data in
args via a GET. You do not need to
include this character in args .
When you submit data using the
args variable, the Integration Server
automatically sets the value of the
Content-Type header to application/
x-www-form-urlencoded. If you want
to explicitly specify a dierent ContentType, you must submit your data using
the string or bytes variable.

table

String Table Optional. Species data that

pub.xml:loadXMLNode will use to construct
a query string to submit to the resource
specied in url .
table is similar to args , but it allows you
to submit unnamed values in a query
string, not just name=value pairs.

webMethods Integration Server Built-In Services Reference Version 9.6

985

Even Header
XML Folder

To specify data using table , create one

row for each value that you want to
submit, where:
The contents of column 0 represent the
name portion of the pair (leave this
column null to submit an unnamed
value, and...
The contents of column 1 represent the
value portion of the pair.
When you submit data using the
table variable, the Integration Server
automatically sets the value of the
Content-Type header to application/
x-www-form-urlencoded. If you want
to explicitly specify a dierent ContentType, you must submit your data using
the string or bytes variable.
Note that when you use table ,
pub.xml:loadXMLNode will automatically:
URL-encode name=value pair, so you
do not need to URL-encode the values
you specify in table .
Insert the "&" character between the
pairs (or unnamed values) that it
constructs, so you do not need to
include it in table .
Prex the entire query string with the
"?" character if it submits the data in
table via the GET method. You do not
need to include this character in table .
string

String Optional. Text that you want

pub.xml:loadXMLNode to submit to the
resource in url .
You can use string to submit data via
either the POST or GET method.
If you use string to specify your data,
make sure that you specify the string
exactly as you want it presented in the
HTTP request. (If you are using the GET
method, make sure you URL-encode the
contents of string ). When performing

webMethods Integration Server Built-In Services Reference Version 9.6

986

Odd Header
XML Folder

a POST the string is submied to the

resource as the body of the document.
bytes

byte[ ] Optional. Data that

pub.xml:loadXMLNode is to submit to the
resource in url . You can use bytes only
to submit data via the POST method.
Note: When you use bytes and another
element (args , table , or string ) to submit
data with pub.xml:loadXMLNode, the service
appends the data from the args , table , or
string element to url . The service appends
args to url rst, table second, and string
last. The service encodes the data from the
bytes element in the body of the post.

stream

java.io.InputStream Optional. Data that

pub.xml:loadXMLNode is to submit to the
resource in url . You can use stream only
to submit data via the POST method.
Note: When you use stream and another
element (args , table , or string ) to submit
data with pub.xml:loadXMLNode, the service
appends the data from the args , table , or
string element to url . The service appends
args to url rst, table second, and string
last. The service encodes the data from the
stream element in the body of the post. If
stream is specied, bytes is ignored.

encoding
headers

String Optional. Name of a registered

IANA character set.

Document Optional. Fields that you want to explicitly override

in the HTTP request header issued by pub.xml:loadXMLNode.
Specify one element for each header eld that you want to set,
where the element's name represents the name of the header
eld, and the element's value represents the value of that
header eld.
If headers is not set, pub.xml:loadXMLNode will use its default
header values.
Note: You do not need to type a colon after the eld name
because pub.xml:loadXMLNode will automatically insert the colon
when it inserts this eld into the request header.

webMethods Integration Server Built-In Services Reference Version 9.6

987

Even Header
XML Folder

If you want to assign specic values to header elds used by

pub.xml:loadXMLNode, keep the following points in mind:
When you specify the value of a header eld, you override
whatever default value webMethods Integration Server
is congured to use for HTTP requests. For example, if
you set the User-Agent header eld to B2B/3.0, the server
uses that value instead of the default value specied by the
wa.net.userAgent parameter.
The pub.xml:loadXMLNode service automatically determines the
value of the Content-Length header eld. You cannot specify
a value for Content-Length.
Be aware that when you submit data using the args or table
elements, pub.xml:loadXMLNode automatically sets the ContentType header eld to application/x-www-formurlencoded.
You cannot override this seing using the headers variable. If
you want to explicitly specify a content type in headers, make
sure to use the string or bytes element to submit your data,
not args or table .
Certain header elds are automatically derived from other
input parameters assigned to pub.xml:loadXMLNode. For
example, the Authorization header eld is automatically
derived from your auth parameter seing. Except for the
Content-Length header eld and the Content-Type header
eld (which, as described above, you cannot override when
submiing data via args or table ), a value that you specify in
headers overrides the value that pub.xml:loadXMLNode might
otherwise derive from other parameter seings.
The pub.xml:loadXMLNode service does not validate data that
you specify in headers . It simply passes it on to the target
server in the request header. Make sure you specify header eld
names and their values correctly. For a complete list of valid
request header elds, see hp://www.w3.org for the latest
HTTP specication published by the W3C.
To specify request headers in headers , create a string element
for each header that you want to specify, where:
The name of the element denes the name header
eld (for example, User-Agent, If- Modied-Since,
Mail_Address), and
The value of the element species the value you want
assigned to that eld.

webMethods Integration Server Built-In Services Reference Version 9.6

988

Odd Header
XML Folder

encoding

String Optional. Character set in which the returned document

is encoded. The parser requires this value in order to interpret
a document correctly. Set to:
autoDetect to determine the document's character set based

on document type, where:

ISO-8859-1 is used for HTML.

UTF-8 is used for XML.
The name of a registered IANA character set to decode
the document using that character set (for example,
ISO-8859-1).
If you do not specify an encoding value, pub.xml:loadXMLNode
decodes the returned document using the following defaults:

expandDTD

If the document is...

It is decoded using...

HTML

ISO-8859-1

XML

UTF-8

String Optional. Flag indicating whether or not

pub.xml:loadXMLNode is to process references to parameter
entities in the returned document's DTD. Set to:
true to expand references to parameter entities to their full

denition.

false to ignore references to parameter entities. This is the

default.

Note: You might want or need to use this variable in cases when
you have a syntactically correct document that causes a parse
error because it violates a denition in an external parameterentity reference. By seing expandDTD to false, you can bypass
the external denition so that pub.xml:loadXMLNode can parse the
document successfully
isXML

String Optional. Flag indicating whether the returned

document is XML or HTML. pub.xml:loadXMLNode must know
this in order to parse a document correctly. Set to:
autoDetect to parse the document based on its type.

When you use this option, pub.xml:loadXMLNode senses the

document's type based on its <!DOCTYPE...\> or <?XML...
\> tag. If it cannot determine a document's type, it parses it
as HTML. This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

989

Even Header
XML Folder

true to parse the document as XML.

false to parse the document as HTML.

Note: : If you know what type of document pub.xml:loadXMLNode

will receive, Software AG recommends that you explicitly set
isXML instead of using autoDetect . It will cut processing time,
because the server will not have to examine the document to
determine its type. The default value is autoDetect .
loadAs

String Optional. Flag that species the form in which you want
pub.xml:loadXMLNode to make the parsed document available to
subsequent services. Set to:
bytes to make the document available as a byte array. This is

the default.

Use this option if the document will be used as input to a

service that operates on whole documents (for example,
pub.xml:queryXMLNode).
stream to make the document available as an InputStream.

Use this option if the document will be used as input to

a service that can process a document incrementally (for
example, pub.xml:getXMLNodeIterator).
failOnHTTPError

String Optional. Determines whether pub.xml:loadXMLNode will

fail (throw an exception) if the requested URL is not loaded
correctly based on an HTTP status code. This parameter
allows for customized error handling of the load failure. Set to:
true to throw a service exception if the URL is not loaded

as indicated by an HTTP status code between 400 and 599,

inclusive.
false to ignore HTTP errors. If there is an error, the HTML

page returned by the web server will be sent to the parser.

This is the default.

expandGeneralEntities String Optional. Flag indicating whether

pub.xml:pub.xml:loadXMLNode should expand references to general
entities in the returned documents DTD. Set to:
true to expand references to general entities to their full

denition. This is the default.

false to ignore references to general entities.

webMethods Integration Server Built-In Services Reference Version 9.6

990

Odd Header
XML Folder

Output Parameters
node

com.wm.lang.xml.Node XML node representing the returned

HTML or XML document.

Usage Notes
If pub.xml:loadXMLNode does not receive a response within the timeout period specied
in the server's wa.net.timeout parameter, it will throw an exception. For information
about the wa.net.timeout parameter, see webMethods Integration Server Administrators
Guide .
If expandGeneralEntities is not specied, Integration Server uses the value in
wa.core.xml.expandGeneralEntities. If wa.core.xml.expandGeneralEntities is not set,
the references to general entities are always expanded.
Use the pub.xml:loadEnhancedXMLNode service to load an XML document and convert it
too an XML node using the enhanced XML parser. For more information about the
legacy XML parser and the enhanced XML parser, see webMethods Integration Server
Administrators Guide.

pub.xml:queryXMLNode
WmPublic. Queries an XML node.
The elds parameter species how data is extracted from the node to produce an output
variable. This output variable is called a "binding," because the elds parameter binds
a certain part of the document to a particular output variable. At run time, this service
must include at least one elds entry. The service must include at least one entry in
elds . The result of each query you specify in elds is returned in a variable whose name
and type you specify.
Input Parameters
node

The XML node or enhanced XML node that you want to

query. This parameter supports the following types of input:
com.wm.lang.xml.Node XML node that you want to query.
An XML node can be produced by pub.xml:loadXMLNode,
pub.xml:xmlStringToXMLNode or an XML content handler.
enhanced XML node The enhanced XML node that
you want to query. An enhanced XML node
can be produced by pub.xml:loadEnhancedXMLNode,
pub.xml:xmlStringToEnhancedXMLNode, or an XML content
handler that receives a document with an xmlFormat is set to

webMethods Integration Server Built-In Services Reference Version 9.6

991

Even Header
XML Folder

enhanced. If you supply an enhanced XML node, you must

use XQL to query the node.
nsDecls

Document Optional. Namespaces associated with any

namespace prexes used element to specify elements in elds/
query . Each entry in nsDecls represents a namespace prex/
URI pair, where a key name represents a prex and the value
of the key species the namespace URI.
For example, to dene the URIs associated with two prexes
called GSX and TxMon, you would set nsDecls as follows:

elds

Document List Optional. Parameters describing how data is to

be extracted from node . Each document in the list contains
parameters for a single query, as follows:
Key

Description

name

String Name to assign to resulting value.

resultType

String Object type that the query is to

yield. The following shows the allowed
values for resultType .
Underlying Value

Corresponding Data
Type

Object

Object

Object[]

Object List

Record

Document

Record[]

Document List

String

String

String[]

String List

String[][]

String Table

webMethods Integration Server Built-In Services Reference Version 9.6

992

Odd Header
XML Folder

query

String Query identifying the data to be

extracted from node .

queryType

String Query language in which query is

expressed. Valid values are WQL and XQL.
If the content of node is an enhanced
XML node, you must set queryType to
XQL.

onnull

String Code indicating what you want

queryXMLNode to do when the result is
null. Set to one of the following:
continue to indicate that all result

values are acceptable for this query

(including null).
fail to indicate that the service should

fail if the result of this query is null

and continue in all other cases.

succeed to indicate that the service

should continue if the result of this

query is null and fail in all other cases.
elds

Document List Parameters that support

recursive execution of bindings. Each
elds list denes bindings for one
level of the output with the top level
being the pipeline and the rst level
down being contents of a document or
document list in the pipeline.

Output Parameters
Document Results from the queries specied in elds . This service returns one element for
each query specied in elds . The specic names and types of the returned elements are
determined by the elds/name and eld/resultType parameters of the individual queries.
Usage Notes
If pub.xml:queryXMLNode fails, it throws a server exception. Common reasons for
queryXMLNode to fail include:
A variable that has no query string assigned to it.
A syntax error in a query string.
A query fails the Allows Nulls test.

webMethods Integration Server Built-In Services Reference Version 9.6

993

Even Header
XML Folder

The node variable does not exist or it is null.

pub.xml:xmlNodeToDocument
WmPublic. Converts an XML node to a document (an IData object).
This service transforms each element and aribute in the XML node to an element in an
IData object. For example:
This service would convert this XML document...
<?xml version="1.0" ?>
<tns:AcctInfo>
xmlns:tns="http://localhost/DerivedAddress/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
<acctNum type=platinum>G97041A</acctNum>
<phoneNum cc=011>216-741-7566</phoneNum>
<address country=USA>
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
</address>
<address country=USA xsi:type="tns:DerivedAddress">
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
<landMark>Besides Ohio River-Bank Square</landMark>
<telNo>001222555</telNo>
</address>
<serialNum>19970523A</serialNum>
<serialNum>20001106G</serialNum>
<serialNum>20010404K</serialNum>
</tns:AcctInfo>

webMethods Integration Server Built-In Services Reference Version 9.6

994

Odd Header
XML Folder

To an IData that looks like this...

Note that:
The XML version aribute is converted to an element named @version.
The resulting document is given the same name as the XML document's root element
(AcctInfo in the example above) and is a child of the document variable that this
service returns.
Simple elements (such as <name> and <rep> in the example above) are converted to
String elements.
Complex elements (that is, elements with children, such as <address> in the
example above) and simple elements that have aributes (such as <acctNum> and
<phoneNum>) are converted to documents (IData objects). Note that keys derived
from aributes are prexed with a "@" character to distinguish them from keys
derived from elements. Also note that when a simple element has an aribute, its
value is placed in an element named *body.
Repeated elements (such as <serialNum>) can be collected into arrays using
the makeArrays and/or arrays parameters. See makeArrays and arrays below for
additional information about producing arrays.

webMethods Integration Server Built-In Services Reference Version 9.6

995

Even Header
XML Folder

While creating a document, the pub.xml:xmlNodeToDocument service assigns a value of

emptyString to the elds that are empty in the document.
The *doctype eld is used to specify the IS document type to which the IData object
should conform. The *doctype eld in the IData object contains the full namespace
name of the IS document type corresponding to the document type referred by the
xsi:type aribute in the XML string.
The document type referred by the *doctype eld should either be created by
importing an XSD le (XML schema) or generated while consuming WSDL for a
provider or consumer web service descriptor. You should also select the Register
document types with schema type option in the New Document Type wizard when
generating a document type from an XML schema.
Input Parameters
node

XML node that is to be converted to a document (IData

object).
This parameter supports the following types of input:
com.wm.lang.xml.Node
org.w3c.dom.Node

arPrex

String Optional. Prex that is to be used to designate keys

containing aribute values. The default is "@". For example,
if you set arPrex to ATT_ and node contained the following
element:
<tx currency=dollars>
<acct>cash</acct>
<amt>120.00</amt>
</tx>

xmlNodeToDocument would convert the currency aribute as

follows:

arrays

String List Optional. Names of elements that are to be

generated as arrays, regardless of whether they appear
multiple times in node . For example, if arrays contained
the following values for the XML document shown in the
example in the description for this service:
rep
address

webMethods Integration Server Built-In Services Reference Version 9.6

996

Odd Header
XML Folder

xmlNodeToDocument would generate element rep as a String

List and element address as a Document List.
Important: If you include namespace prexes in the element
names that you specify in arrays , you must dene the
namespaces associated with those prexes in nsDecls .
makeArrays

String Optional. Flag indicating whether you want

xmlNodeToDocument to automatically create an array for every
element that appears in node more than once. Set to:
true to automatically create arrays for every element that

appears more than once in node . This is the default.

false to create arrays for only those elements specied in

arrays or dened as arrays in the document type specied

in documentTypeName .
Important: You must set makeArrays to false when using
documentTypeName to dene the structure of an element.
Otherwise, an exception will be thrown at run time.
collect

Document Optional. Elements that are to be placed into a

new, named array (that is, a "collection"). Within collect , use
key names to specify the names of the elements that are to
be included in the collection. Then set the value of each key
to specify the name of the collection in which you want that
element placed. For example, if you wanted to place the
<name> and <rep> elements in an array called originator,
you would set collect as follows:
Key

Value

name

originator

rep

originator

If the set of elements in a collection are all simple elements,

a String List is produced. However, if the set is made up of
complex elements, or a combination of simple and complex
elements, a Document List is produced. When this is the
case, each member of the array will include a child element
called *name that contains the name of the element from
which that member was derived.
You may optionally include namespace prexes in the
element names that you specify in collect ; however, if you

webMethods Integration Server Built-In Services Reference Version 9.6

997

Even Header
XML Folder

do, you must dene the namespaces associated with those

prexes in nsDecls .
Important: You cannot include an element in more than one
collection.
nsDecls

Document Optional. Namespace prexes to use for the

conversion. This parameter species the prexes that will
be used when namespace-qualied elements are converted
to key names in the resulting IData object. For example, if
you want elements belonging to a particular namespace
to have the prex GSX in the resulting IData (for example,
GSX:acctNum), you would associate the prex GSX with that
namespace in nsDecls . (This is important because incoming
XML documents can use any prex for a given namespace,
but the key names expected by a target service or MAP step
on the Integration Server will have a xed prex.)
Namespace prexes in nsDecls also dene the prexes used
by the arrays , documents , documentTypeName , and collect
parameters.
Each entry in nsDecls represents a namespace prex/URI
pair, where a key name represents a prex and the value of
the key species the namespace URI.
For example, to dene the URIs associated with two prexes
called GSX and TxMon, you would set nsDecls as follows:

documents

String List Optional. Names of any simple elements that are

to be generated as documents (IData objects) instead of
Strings. The document produced for each element specied
in documents will have the same name as the source element
from which it is derived. It will contain a String element
named *body that holds the element's value.
For example, if documents contained the Strings name and
rep and the source document contained the following:
.
.
.
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
.
.
.

xmlNodeToDocument would produce the following:

webMethods Integration Server Built-In Services Reference Version 9.6

998

Odd Header
XML Folder

Note: If you include namespace prexes in the element names

that you specify, you must dene the namespaces associated
with those prexes in nsDecls .
documentTypeName

String Optional. Fully qualied name of the document type

that species the structure that is to be imposed on the
resulting document. You can use this parameter to explicitly
specify the order and dimensionality of elements. It is an
alternative to using makeArrays and arrays to specify which
elements are to be generated as arrays.
For example, if you had the XML document shown in
the example in this service's description, and you wanted
the <name> and <rep> elements to be generated as String
lists, you would dene them as String Lists elds in a
document type and then specify that document type in
documentTypeName .
Note: The document type specied in documentTypeName
does not need to specify every element that will appear in
the resulting document. It only needs to specify the elements
whose structure you want to explicitly set. However, if you
include namespace prexes in the element names that you
specify, you must dene the namespaces associated with those
prexes in nsDecls .
This service always converts XML nodes to String or
Document object elds. It does not generate constrained
objects (for example, Floats or Integers), even if the elds in
the specied document are dened as constrained objects.
Important: When you use documentTypeName , set makeArrays
to false and do not set arrays and documents . Otherwise,
xmlNodeToDocument will throw an exception at run time.

mixedModel

String Optional. Flag specifying how mixed-content elements

(elements containing both text values and child elements)
are to be converted. The following is an example of a mixedcontent element:
<comment>
This job is <status>pending</status>. Estimated
completion date is <edc>Feb 14, 2000</edc>.
</comment>

webMethods Integration Server Built-In Services Reference Version 9.6

999

Even Header
XML Folder

Set to:
true to place top-level text in an element named *body.

This seing would produce the following IData for the

<comment> element shown above:

Important: When you set mixedModel to true, you must also use
documentTypeName to specify a document type that describes
the structure of the IData that you want xmlNodeToDocument to
produce. Within the document type, mixed-content elements
must be dened as documents that include a String eld
named *body.
false to omit top-level text and include only the child

elements from mixed-content elements. This seing would

produce the following IData for the <comment> element
shown above:

preserveUndeclaredNS

String Optional. Flag indicating whether or not Integration

Server keeps undeclared namespaces in the resulting
document (IData). An undeclared namespace is one that is
not specied as part of the nsDecls input parameter.
Set to:
True to preserve undeclared namespaces in the resulting

document. For each namespace declaration in the XML

document that is not specied in the nsDecls parameter,
Integration Server adds the xmlns aribute as a String
variable to the document (IData). Integration Server gives
the variable a name that begins with "@xmlns" and assigns
the variable the namespace value specied in the XML
document. Integration Server preserves the position of the
undeclared namespace in the resulting document.
False to ignore namespace declarations in the XML

document that are not specied in the nsDecls parameter.

This is the default.

webMethods Integration Server Built-In Services Reference Version 9.6

1000

Odd Header
XML Folder

preserveNSPositions

String Optional. Flag indicating whether or not Integration

Server maintains the position of namespaces declared in the
nsDecls parameter in the resulting document.
Set to:
True to preserve the position of namespaces declared in

nsDecls in the resulting document. For each namespace

specied in the nsDecls parameter, Integration Server adds
the xmlns aribute to the document (IData) as a String
variable named "@xmlns:NSprex " where "NSprex " is
the prex name specied in nsDecls . Integration Server
assigns the variable the namespace value specied in the
XML document. This variable maintains the position of the
xmlns aribute declaration within the XML document.
False to not maintain the position of the namespace

declarations specied in nsDecls in the resulting document.

This is the default.
Output Parameters
document

Document Document (IData object) representation of the nodes

and aributes in node.

Usage Notes
If the IS document type in documentTypeName accurately represents the content model
for the complex type from which it was created (the Model type property value is not
Unordered), when Integration Server converts an XML node to a document (IData),
Integration Server matches up the contents of an element in the XML node with the
content model of the IS document type. If a mismatch occurs and Integration Server
is unable to map the XML node contents to the IS document type, Integration Server
appends the remaining data to the resulting document (IData). Integration Server
stops aempting to map the XML node content to a eld in the IS document type. This
mismatch does not result in an error at the time the document is created. However, the
document would fail validation by the pub.schema:validate service.
Following are examples of XML documents and the documents (IData objects) that
xmlNodeToDocument would produce.
XML Document

Output from xmlNodeToDocument

<myDoc>
<e1>e1Value</e1>
</myDoc>

webMethods Integration Server Built-In Services Reference Version 9.6

1001

Even Header
XML Folder

XML Document

Output from xmlNodeToDocument

<?xml version="1.0" encoding="UTF-8"

standalone="no"?>
<myDoc>
<e1>e1Value</e1>
</myDoc>

<?xml version="1.0" encoding="UTF-8"

standalone="no"?>
<myDoc>
<e1 e1Attr="attrValue">e1Value</e1>
</myDoc>

<?xml version="1.0" encoding="UTF-8"

standalone="no"?>
<myDoc>
<e1>e1Value</e1>
<e2>e2Value</e2>
</myDoc>

<?xml version="1.0" encoding="UTF-8"

standalone="no"?>
<myDoc>
<e1>e1Value1</e1>
<e2>e2Value</e2>
<e1>e1Value2</e1>
</myDoc>

<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>

Note: This example assumes that

makeArrays is set to true. Note that e1
was created as a document list, which
webMethods Integration Server Built-In Services Reference Version 9.6

1002

Odd Header
XML Folder

XML Document

Output from xmlNodeToDocument

holds both <e1> elements from the XML
document.

<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>

Note: This example assumes that

makeArrays is set to false and that
wa.server.xml.xmlNodeToDocument.
keepDuplicates is set to true (the default).
Note that both<e1> elements from the
source XML are retained.
<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>e2Value</e2>
<e1 e1Attr="attrValue2">e1Value2</e1>
</myDoc>

Note: This example assumes that

makeArrays is set to false and that
wa.server.xml.xmlNodeToDocument.
keepDuplicates is set to false. Note
that only the last <e1> element in the
source XML was retained in the resulting
document.

webMethods Integration Server Built-In Services Reference Version 9.6

1003

Even Header
XML Folder

XML Document

Output from xmlNodeToDocument

<?xml version="1.0"
encoding="UTF-8"?>
<myDoc>
<e1 e1Attr="attrValue1">e1Value1</e1>
<e2>
<e3>e3Value</e3>
<e4 e4Attr="attrValue4"
e4Attrb="attrValue4b">e4Value
</e4>
</e2>
</myDoc>

<?xml version="1.0" encoding="UTF-8"

standalone="no"?>
<tns:AcctInfo>
xmlns:tns="http://localhost/Derived
Address/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance" >
<myDoc>
<e1>e1Value</e1>
</myDoc>
<myDoc xsi:type="tns:DerivedDoc">
<e1>e1Value</e1>
<e2>e1Value</e2>
</myDoc>
</tns:AcctInfo>

pub.xml:xmlStringToEnhancedXMLNode
WmPublic. Converts an XML document (represented as a String, byte[ ], or
InputStream) to an org.w3c.dom.Node object using the enhanced XML parser.
An DOM node is a special representation of an XML document that can be consumed
by any program that uses standard DOM APIs. The pub.xml:xmlNodeToDocument service
accepts a DOM object as input.
Input Parameters
xmldata

String Optional. String containing the XML document to

convert to an XML node.
Note: If you specify xmldata , do not specify $ledata or
$lestream .

$ledata

byte[ ] Optional. byte[ ] containing the XML document to

convert to an XML node.

webMethods Integration Server Built-In Services Reference Version 9.6

1004

Odd Header
XML Folder

Note: If you specify $ledata , do not specify xmldata or

$lestream .
$lestream

java.io.InputStream Optional. InputStream containing the XML

document to convert to an XML node.
Note: If you specify $lestream , do not specify xmldata or
$ledata .

encoding

String Optional. Character encoding in which text is

represented. Specify UTF-8 for XML les and ISO-8859-1 for
HTML les. To have the parser aempt to detect the type of
encoding, specify autoDetect (the default, if encoding is not
specied).

inputProcessing

Document. Optional. Contains a set of input parameters

that instruct Integration Server how to read the XML
document. The elds are comparable to options in the
javax.xml.stream.XMLInputFactory class.
Key

Description

isValidating

String Optional. Determines whether

Integration Server performs DTD
validation. Set to:
true to perform DTD validation.
false to disable DTD validation. This is

the default.
isNamespaceAware

String Optional. Determines whether

Integration Server provides namespace
processing for XML 1.0 support while
parsing the XML document. Set to:
true to enable namespace processing.

This is the default.

false to disable namespace processing.

isCoalescing

String Optional. Determines whether

Integration Server coalesces adjacent
character data while parsing the XML
document. Set to:
true to coalesce adjacent character data.

webMethods Integration Server Built-In Services Reference Version 9.6

1005

Even Header
XML Folder

false to indicate that Integration Server

does not coalesce adjacent character

data. This is the default.
isReplacingEntity
References

String Optional. Determines whether,

while parsing the XML document,
Integration Server replaces internal entity
references with replacement text and
treats them as characters. Set to:
true to replace entity references. This is

the default.

false to indicate entity references will

not be replaced.
isSupporting
ExternalEntities

String Optional. Determines whether

Integration Server resolves external
parsed entities while parsing the XML
document. Set to:
true to resolve external parsed entities.
false to indicate Integration Server

does not support external parsed

entities.

The JVM in which Integration Server runs

determines the default.
supportDTD

String Optional. Determines whether

Integration Server supports DTDs while
parsing the XML document. Set to:
true to support DTDs while parsing the

XML document. This is the default.

false to disable support of DTDs while

parsing the XML document.

partitionSize

String Optional. Species the size, measured in bytes, of the

partitions on the heap where the enhanced XML parser stores
parsed document information. Specify a sux of k to
indicate kilobytes or m to indicate megabytes. For example,
10k or 10m.
If you do not specify a value, Integration Server uses the
default partition size value specied on the Settings > Enhanced
XML Parsing screen in Integration Server Administrator.

webMethods Integration Server Built-In Services Reference Version 9.6

1006

Odd Header
XML Folder

Output Parameters
org.w3c.dom.Node XML node representing the returned XML
document. This object can be used as input to webMethods
services that consume XML nodes in the form of a DOM
object.

node

Usage Notes
The input parameters xmldata , $ledata , and $lestream are mutually exclusive. Specify
only one of the preceding parameters. Integration Server checks the parameters in
the following order, using the value of the rst parameter that has a specied value:
$ledata , $lestream , and xmldata .
Use the pub.xml:xmlStringToXMLNode service to convert an XML document to an XML node
using the legacy XML parser. For more information about the legacy XML parser and
the enhanced XML parser, see webMethods Integration Server Administrators Guide.
Keep the following information in mind when specifying a partitionSize
The partitionSize is a hint for the enhanced XML parser so that it can estimate the
amount of heap space needed to parse the document. Often, it not possible to
determine the size of an inbound XML document before parsing.
As a general rule, Software AG recommends a partitionSize that is 1/2 the size of the
unparsed XML document.
A partitionSize that is considerably larger than 1/2 the size of the unparsed XML
document causes the enhanced XML parser to consume more heap space than
necessary but might also improve throughput. However, this can impact the
overall performance of Integration Server.
A partitionSize that is considerably smaller than 1/2 the size of the unparsed XML
document causes the enhanced XML parser to create a large number of partitions
to parse the document. While this might use less heap space, it may reduce the
throughput of the parser.
A partitionSize that is three times smaller or three times larger than 1/2 the size of
the unparsed XML document will likely have lile impact on the performance.
At run time, the enhanced XML parser overrides a partitionSize that consumes all of
the available heap space.
At run time, if the partitionSize results in an initial heap allocation that exceeds
the single document limit set in the Maximum heap allocation for any single document
eld the limit for all documents set in the Maximum heap allocation for all documents
combined eld, the enhanced XML parser reduces the partition size automatically.
For more information about heap allocation limits for the enhanced XML parser, see
webMethods Integration Server Administrators Guide

webMethods Integration Server Built-In Services Reference Version 9.6

1007

Even Header
XML Folder

If you do not specify partitionSize , the enhanced XML parser uses the default
specied in the Default partition size eld on the Settings > Enhanced XML Parsing page in
Integration Server Administrator.

pub.xml:xmlStringToXMLNode
WmPublic. Converts an XML document (represented as a String, byte[ ], or
InputStream) to an XML node.
An XML node is a special representation of an XML document that can be consumed
by the Integration Server. Most webMethods services that operate on XML documents
require an XML node as input.
Input Parameters
xmldata

String Optional. String containing the XML document to

convert to an XML node.
Note: If you specify xmldata , do not specify $ledata or
$lestream .

$ledata

byte[ ] Optional. byte[ ] containing the XML document to

convert to an XML node.
Note: If you specify $ledata , do not specify xmldata or
$lestream .

$lestream

java.io.InputStream Optional. InputStream containing the XML

document to convert to an XML node.
Note: If you specify $lestream , do not specify xmldata or
$ledata .

encoding

String Optional. Character encoding in which text is

represented. Specify UTF-8 for XML les and ISO-8859-1 for
HTML les. To have the parser aempt to detect the type of
encoding, specify autoDetect (the default, if encoding is not
specied).

expandDTD

String Optional. Flag indicating whether references to

parameter entities in the XML document's DTD are to be
processed. Set to:
true to expand references to parameter entities to their full

denition.

webMethods Integration Server Built-In Services Reference Version 9.6

1008

Odd Header
XML Folder

false to ignore references to parameter entities. This is the

default.
isXML

String Optional. Flag specifying whether the input document

is XML or HTML. (xmlStringToXMLNode must know this so that it
can parse the document correctly.) Set to:
autoDetect to parse the document based on its type. When

you use this option, xmlStringToXMLNode detects the document's

type based on its <!DOCTYPE...\> or <?XML...\> tag. If it
cannot determine a document's type, it parses it as HTML.
This is the default.
true to parse the document as XML.
false to parse the document as HTML.

expandGeneralEntities String Optional. Flag indicating whether

pub.xml:xmlStringToXMLNode should expand references to general
entities in the XML documents DTD. Set to:
true to expand references to general entities to their full

denition. This is the default.

false to ignore references to general entities.

Output Parameters
node

com.wm.lang.xml.Node XML node representation of the XML

document in xmlData . This object can be used as input to
webMethods services that consume XML nodes.

Usage Notes
The input parameters xmldata , $ledata , and $lestream are mutually exclusive. Specify
only one of the preceding parameters. Integration Server checks the parameters in the
following order, using the value of the rst parameter with a specied value: $ledata ,
$lestream , and xmldata .
If expandGeneralEntities is not specied, Integration Server uses the value in
wa.core.xml.expandGeneralEntities. If wa.core.xml.expandGeneralEntities is not set,
the references to general entities are always expanded.
Use the pub.xml:xmlStringToEnhancedXMLNode service to convert an XML document to an
XML node using the enhanced XML parser. For more information about the legacy XML
parser and the enhanced XML parser, see webMethods Integration Server Administrators
Guide.

webMethods Integration Server Built-In Services Reference Version 9.6

1009

Even Header

webMethods Integration Server Built-In Services Reference Version 9.6

1010

Odd Header
XSLT Folder

42 XSLT Folder
Summary of Elements in this Folder .......................................................................................

webMethods Integration Server Built-In Services Reference Version 9.6

1012

1011

Even Header
XSLT Folder

You use the elements in the XSLT folder to transform XML into a byte array, le, or XML
node, and to maintain the XSLT stylesheet cache.

Summary of Elements in this Folder

The following elements are available in this folder:
Element

Package and Description

pub.xslt.Transformations:transformSerialXML

WmXSLT. Uses an XSLT stylesheet

to transform XML, then stores the
transformed XML in a byte array, le, or
XML node.

pub.xslt.Cache:removeAllTemplates

WmXSLT. Clears the XSLT stylesheet

cache.

pub.xslt.Cache:removeTemplate

WmXSLT. Removes one stylesheet from

the XSLT stylesheet cache.

The WmXSLT package also comes with sample services that show you how to use the
public services.

pub.xslt.Transformations:transformSerialXML
WmXSLT. Uses an XSLT stylesheet to transform XML, then stores the transformed XML
in a byte array, le, or XML node.
To optimize performance, the service stores the XSLT stylesheet in a cache so the
stylesheet will be instantly available to the service for later runs.
Input Parameters
stylesheetSystemId

String URI (simple le path or URL) for the XSLT stylesheet to

use.

systemId

String URL of the XML to transform. If you specify this

parameter, do not specify the lename , bytes , or xmlStream
parameter.

lename

String Fully qualied name of the le that contains the XML to

transform. The le must be located on the local machine. If you

webMethods Integration Server Built-In Services Reference Version 9.6

1012

Odd Header
XSLT Folder

specify this parameter, do not specify the systemId , bytes , or

xmlStream parameter.
bytes

byte[] XML to transform. If you specify this parameter, do not

specify the systemId , lename , or xmlStream parameter.

xmlStream

Input stream XML to transform. If you specify this parameter, do

not specify the systemId , lename , or bytes parameter.

xslParamInput

Document Optional. Name/value pairs to pass to the stylesheet.

See the webMethods Service Development Help for instructions on
seing up a stylesheet to work with this parameter.

resultType

String Tells Designer what to transform the XML into. Must be

one of these values:
bytes to transforms the XML into a byte array.
file to transforms the XML into a le. If you specify file,

you must also specify the outFileName parameter.

xmlNode to transforms the XML into an XML node.

outFileName

String Fully qualied name of the le in which to store the

transformed XML. The le must be located on the local
machine. Use this parameter only if you specied file on the
resultType parameter.

useCompiling
Processor

Boolean. Optional. Species whether to use the Xalan compiling

processor (XSLTC), which creates and uses compiled
stylesheets or translets . Set to:
true to use the org.apache.xalan.xsltc.trax.TransformerFactoryImpl

class as a transformer factory.

false to use the transformer factory that is specied on the

home page of the WmXSLT package. This is the default.

If no translet currently exists for the stylesheet, the processor

creates one. If a translet exists and the stylesheet has changed
since the translet was created, the processor replaces the
existing translet with a new one. If the stylesheet has not
changed since the translet was created, the processor reuses the
existing translet.
If the stylesheetSystemId input parameter species a simple le
path, the service writes the translet to the same folder in which
the stylesheet for your XSLT service resides.

webMethods Integration Server Built-In Services Reference Version 9.6

1013

Even Header
XSLT Folder

If the stylesheetSystemId input parameter species a URL, the

service writes the translet to memory. As a result, the translet
will not survive Integration Server restart.
loadExternalEntities

String Optional. Species whether or not to load external

entities (le URIs, HTTP URLs, and so on) referenced in the
XML that the service receives or in the XSLT stylesheet the
service uses to transform the XML. Set to:
true to load content from all external entities that are

referenced in the XSLT stylesheet or in the XML. This is the

default.
false to not load content from external entities that are

referenced in the XSLT stylesheet or in the XML. Use this

seing to prevent aacks from external entities by blocking
those entities.
Important: To help prevent an external entity aack in a
production environment, set loadExternalEntities to false in each
instance of the transformSerialXML service.
Output Parameters
bytes

byte[] Byte array that contains the transformed XML. The

service places the byte array in the pipeline so that subsequent
services can use it. This value is present only if you specied
bytes in the resultType input parameter.

node

com.wm.lang.xml.Node Node that contains the transformed

XML. The service places the XML node in the pipeline so that
subsequent services can use it. This value is present only if you
specied xmlNode in the resultType input parameter.

xslParamOutput

Document Document that contains name/value pairs that were

returned by the stylesheet. The service places the document in
the pipeline so that subsequent services can use it. This value
is present only if you add name/value pairs to it within your
stylesheet.
See the section on passing name/value pairs from the stylesheet
to the pipeline in webMethods Service Development Help for
instructions on seing up your stylesheet to work with this
parameter.

webMethods Integration Server Built-In Services Reference Version 9.6

1014

Odd Header
XSLT Folder

Example
You want to transform an XML document named cdCatalog.xml into an HTML
document using an XSLT stylesheet named cdCatalog.xsl. You would pass the
transformSerialXML service these values:
Input Parameters
stylesheetSystemId

http://localhost:5555/WmXSLT/samples/xdocs/
cdCatalog.xsl

systemId

http://localhost:5555/WmXSLT/samples/xdocs/
cdCatalog.xml

resultType

bytes

The service transforms the XML stream into a byte array containing an HTML document
and puts the byte array in the pipeline. You could convert the byte array into a String
using the Integration Server built-in service pub.string:bytesToString, then display the String
using a dynamic server page (DSP). For information about using DSPs, see Dynamic
Server Pages and Output Templates Developers Guide.
Usage Notes
If loadExternalEntities is set to false, you can have the service load, read, and transform
content from a trusted external entity by doing one of the following:
Place the trusted external entity le in the Integration Server installation directory or
subdirectories.
Include the trusted external entity in the list of trusted entities identied in the server
parameter wa.core.xml.allowedExternalEntities. For more information about this
parameter, see webMethods Integration Server Administrators Guide.
If loadExternalEntities is not specied in the service signature, Integration Server checks
the value of the server parameter wa.core.xml.expandGeneralEntities. If this parameter
is set to false, the transformSerialXML service blocks all external entities that are not
included in the list of trusted entities specied in wa.core.xml.allowedExternalEntities.
For more information about wa.core.xml.expandGeneralEntities, see webMethods
Integration Server Administrators Guide.

pub.xslt.Cache:removeAllTemplates
WmXSLT. Clears the XSLT stylesheet cache.

webMethods Integration Server Built-In Services Reference Version 9.6

1015

Even Header
XSLT Folder

Input Parameters
None.
Output Parameters
message

String Indicates whether the service was able to clear the cache.

pub.xslt.Cache:removeTemplate
WmXSLT. Removes one stylesheet from the XSLT stylesheet cache.
Input Parameters
stylesheetSystemId

String URI for the XSLT stylesheet to remove from the cache.

Output Parameters
message

String Indicates whether the service was able to remove the

stylesheet from the cache.

webMethods Integration Server Built-In Services Reference Version 9.6

1016

M
Index

Index
A

absoluteValue 494
access permissions assigned to built-in services 24
ACLs assigned to built-in services 24
action 810
activatePackage 546
addBodyBlock 721
addBodyEntry 777
addBodyPart 517
addComplexTask 623
addFaultBlock 724
addFloatList 494
addFloats 495
addHeaderBlock 726
addHeaderEntry 779
adding
body parts to MIME messages 517
documents to list 485
entries into a data store 845
MIME message headers 521
numeric values 494, 495, 496, 497
strings to list 486
addIntList 496
addInts 497
addItemToVector 484
addMimeHeader 521
addObjects 497
addOnetimeTask 626
addReleaseRegistryEntry 605
addRepeatingTask 628
addSubscriber 242
addTrailer 781
alarm specification 245
alarmInfo document type 246
appending data to a remote file 92
appendToDocumentList 485
appendToStringList 486
arithmetic services 492
ART folder 28
ART services 28
asynchronous call to a remote server 601
asynchronous request/reply
delivering request 569
description of 570, 585
publishing request 583
publishing request to a specific client 569

retrieving reply 589

audit specification 247
auditError event 248
auditErrorInfo document type 250
auditInfo document type 251

backupPackage 547
base64 Decode 860
base64Encode 860
binding
output template to Values object 618
BPEL folder 511, 933
byte 390
byte array from string 871
bytesToDocument 223
bytesToFile 306
bytesToStream 391
bytesToString 861

Cache folder 53
calculateDateDifference 181
call 194
calling stored procedures 194
callStackItem document type 252
cancelTask 631
canonical document, definition 885
canonical keys
creating 885
inserting 889
retrieving 887
cd 92, 135
cdgrp 136
cdls 93, 107
certificate chain 663
certs-only S/MIME Message
creating 697
extracting certificates from 702
changing the working directory 92, 135
character sequence, indexing first occurrence 863
checkFileExistence 307
chmod 136
chown 137
clear pipeline 356
clearing transactional state 196
clearKeyAndChain 663
clearTransaction 196

webMethods Integration Server Built-In Services Reference Version 9.6

1017

M
Index

Client folder 84
close 392
close connection 197
closeAll 198
closeLatch 882
closeStore 846
closing database connection 197
committing changes to a database 198
commitTransaction 47
compatibility mode 947
complex tasks
adding to scheduler 623
updating to scheduler 639
components
XML schema definitions 657
concatenating
array of strings 866
strings 861
connections
creating 199
containsKey 384
content type, getting from MIME message 529
converting
string list to document list 487
XML nodes to IData objects 994
converting to
InputStream 390
convertToString service 320
convertToValues service 325
copyFile 307
createByteArray 392
createCertsOnlyData 697
createDocumentType service 335
createEncryptedData 697
createFFDictionary service 335
createHashtable 385
createJMSTrigger 893
createMessageDigest 678
createMimeData 523
createSignedAndEncryptedData 557, 698
createSignedData 559, 700
createSoapData 787
createTrigger 907
createXReference 885
createXSD 651
creating MIME messages 523
cross-references
creating 885
deleting by object ID 886

deleting individual records 886

inserting 889
current VCS user
removing 955
setting 956
currentNanoTime 182

da teTimeFormat 185
data
converting 390
waiting for delivery 879
data stores
adding entries 845
closing 846
deleting 846
inserting entries 852
registering 853
removing entries 854
retrieving values 847
unlocking entries 852, 855
unregistering 846
updating entries 852
database connection, closing 197, 198
database services 192
databases
clearing transactional state 196
closing connections 197, 198
committing changes 198
creating connections 199
deleting rows 201
discarding changes 216
invoking stored procedures 194
querying 215
retrieving names of stored procedures 208
retrieving tables 211
starting a transaction 217
datatypes in XML schemas 657, 657
Date folder 175
dateBuild 182
dates
converting formats 185
formatting 187
invalid dates 180
returning current 188, 188
symbols used for 176
time zones 177
dateTimeBuild 183

webMethods Integration Server Built-In Services Reference Version 9.6

1018

M
Index

debug log 356

debugging services 354
decoding URL-encoded strings 874
decrypting
MIME messages 702
S/MIME messages 559
deepClone 944
default key, associating with invoked services 663
deleteByObjectId 886
deleteFFDictionary service 336
deleteFFDictionaryEntry service 337
deleteFFSchema service 338
deleteFile 308
deleteJMSTrigger 916
deleteReleaseRegistryEntry 606
deleteStore 846
deleteSubscriber 252
deleteXReference 886
deleting
cross-reference by object ID 886
cross-references 886
data stores 846
files in working directory 94
rows from a database 201
subscribers from subscription list 252
deliver service 567
deliverAndWait service 568
digital signatures
attaching to MIME messages 700
verifying 561, 677, 703
dir 94
directory
changing 92
disableConnection 31
disableListener 34
disableListenerNotification 39
disablePackage 548
disablePollingNotification 39
distributeViaFTP 607
distributeViaSvcPull 608
distributeViaSvcPush 609
divideFloats 498
divideInts 499
divideObjects 500
docume ntResolverSpec specific ation 571
Document folder 221
document processing
resuming 921
suspending 928

document resolver spec, for JMS messages 412

document retrieval
resuming 924
suspending 930
document services 222
document types
alarmInfo 246
audit error event information 250
audit event information 251
callStackItem 252
exception information 266
gdEndInfo 268
gdStartInfo 269
portStatusInfo 286
QName 799
replicationInfo 288
sessionEndInfo 293
sessionExpireInfo 294
sessionStartInfo 296
statInfo 298
txEndInfo 300
txStartInfo 302
documentation
using effectively 21
documentListToDocument 224
documents
adding to list 485
constructing from a list of documents 224
converting a byte array to a document 223
converting a document to an array of bytes 226
converting list from string list 487
converting to a String 230
converting to JSON strings 479
converting to XML strings 961
creating from JSON streams 480
creating from JSON strings 481
delivering 567
delivering and waiting for reply 568
expanding contents into a list of documents 228
publishing 580
publishing and waiting for reply 582
replying to 586
resolving status of 571
retrieving redelivery count 578
synchronizing 588
waiting for 589
documentToBytes 226
documentToDocumentList 228
documentToJSONString 479

webMethods Integration Server Built-In Services Reference Version 9.6

1019

M
Index

documentToXMLString 961
documentToXMLValues 230
dynamic text generation 618

eda
event 254
eventToDocument 255
schema_event 257
elapsedNanoTime 186
elements, number of in a list 487
enableConnection 31
enableListener 35
enableListenerNotification 39
enablePackage 549
enablePollingNotification 40
encoding schema, SOAP 777
encoding schema,SOAP, version 1.2 777
encoding URL strings 875
encrypting MIME messages 557, 697
ending guaranteed delivery transactions 597
Enterprise Gateway specification 666
entries
inserting into repository 845
envelope schema, SOAP 777
envelope schema,SOAP, version 1.2 777
envelope stream, generating from MIME message
529
envelope, for published documents 573
error event 263, 263
error notification document type 591
error service 591
event
creating subscription for 242
sending 257, 283
event document type 254
Event folder 237
event handle rs
get list of subscribers 270
event handlers 238
alarm specification 245
alarmInfo document type 246
audit specification 247
auditError specification 248
auditErrorInfo document type 250
auditInfo document type 251
callStackItem document type 252
exception specification 264

exceptionInfo document type 266

gdEnd specification 267
gdEndInfo document type 268
gdStart specification 268
gdStartInfo document type 269
get list of event types 270
modify subscriber info 278
portStatus specification 286
portStatusInfo document type 286
reload event manager settings 287
replication specification 287
replicationInfo document type 288
save event manager settings 289
sessionEnd specification 292
sessionEndInfo document type 293
sessionExpire specification 294
sessionExpireInfo document type 294
sessionStart specification 295
sessionStartInfo document type 296
stat specificati on 296
statInfo document type 298
subscriptions for 242
txEnd specification 300
txEndInfo document type 300
txStart specification 301
txStartInfo document type 302
unsubscribing from an event 252
eventToDocument 255, 282
exception specification 264
exceptionInfo document type 266
exceptions for retry 374
exceptions, last trapped in a flow 357
execSQL 203
executeOSCommand 945
exitUnableToUnderstand 789
extensions
files with no extension, using with FTP put
command 107
extracting MIME content 526
extracting MIME message headers 527, 531

faultTo 810
FFDictionary IS document type 338
FFSchema IS document type 341
fields, removing from pipeline 356
File folder 303
file object, templates 616

webMethods Integration Server Built-In Services Reference Version 9.6

1020

M
Index

file services 304, 402

files
appending data to 92
change owner 137
change permissions 136
deleting 94
listing 93, 94, 102, 107, 140
multiple delete 103
multiple get 104
multiple transfer 104
renaming 108
retrieving 95
saving pipeline contents 364
transferring 105
transferring SFTP 141
findDependants service 344
finding universal names 938
findReferences service 344
fire-and-forget call 600
floating point numbers
adding 494
dividing 498
multiplying 501
subtracting 506
Flow folder 353
flow services 354
forcing a response string 366
formatDate 187
FormatService service 331
formatting
array of strings 866
number to numeric pattern 867
freeXMLNode 968
from 812
FTP
changing directory and listing files 93, 107
changing working directory 92, 135
client actions 88
delete file 94
executing non-standard FTP commands 108
files with no extension 107
filetransfer 105
ftp_no_extensionkey 107
listing files 94, 102, 140
login 98
logout 101, 139
multiple file delete 103
multiple file get 104
multiple file transfer 104

renaming files 108

retrieving files 95
session info 109
transferring files 105
FTP servers, submitting requests to 110

gdEnd specification 267

gdEndInfo document type 268
gdStart specification 268
gdStartInfo document type 269
generateDocumentTypesFromWSDL 733
generateReplicationEvent 609
generateUUID 947
get 385
get (FTP) files 95
get (SFTP) files 137
getActor 790
getBody 791
getBodyBlock 735
getBodyBlockQNames 737
getBodyEntries 791
getBodyPartContent 526
getBodyPartHeader 527
getCanonicalKey 887
getCertificateInfo 679
getConnectionStatistics 32
getContentType 529
getCurrentDate 188
getCurrentDateString 188
getDocument 792
getEncoding 793
getEnvelopeStream 529
getEventTypes 270
getFaultBlock 738
getFFDictionaryAsXML service 345
getFFDictionaryEntryAsXML service 346
getFFSchemaAsXML service 346
getFile 309
getHeader 793
getHeaderEntries 794
getInitialSOAPRequest 746
getLastError 357
getLocalReleasedList 609
getMessageAddressingProperties 747
getMimeHeader 531
getMustUnderstand 795
getNativeId 888

webMethods Integration Server Built-In Services Reference Version 9.6

1021

M
Index

getNextXMLNode 969
getNumParts 532
getPoolInfo 402
getPrimaryContentType 533
getProcInfo 207
getProcs 208
getQName 796
getRedeliveryCount service 578
getRemoteReleasedList 610
getSession 359
getStatus 597
getSubContentType 534
getSubscribers 270
getSupportedEncodings 334
getTableInfo 210
getTables 211
getTaskIDs 631
getTaskInfo 632
getTrailer service 797
getTransportInfo 359
getUsers 954
getWebServiceInvocationProperties 753
getWorkingDays 189
getXMLNodeIterator 970
getXMLNodeType 973
guaranteed delivery services 594
guaranteed delivery transactions
ending 597
getting status of 597
invoking service 598
restarting 599
retrieving results of 599
starting 600
guaranteed one-way call 600

response headers 373

submitting requests to servers 110

IData objects
converting to JSON strings 479
converting to XML strings 961
creating from JSON streams 480
creating from JSON strings 481
IDs, retrieving list of 631
indexOf 863
InputStream, converting to byte 390
inserting table rows 213
insertXReference 889
installPackage 549
integers
adding 496
dividing 499
multiplying 503
subtracting 508
invalid dates 180
invoke, guaranteed delivery service 598
invokeService 360
invoking
remote services 594
report services 616
stored procedures 194
invoking a service
guaranteed delivery 601
protocols used 375
remote webMetho ds Int egration Server 595
IO services 390
IS Internal 840
isLatchClosed 883
iterating through XML nodes 970

handling large flat files

iterator variable of convertToValues service 326
Hashtable folder 383
hashtable services 384
header fields, adding to MIME object 521
headers, changing HTTP 110
HTMLDecode 862
HTMLEncode 862
HTTP
changing header variables 110
response code 370
response header 370

JDBC folder 401

JDBC pools 402
JDBC-related services 192
JMS
sending an event 257, 283
JMS folder 405
JMS messages
send batch 458
sending multiple 458
JMS trigger
create 893

webMethods Integration Server Built-In Services Reference Version 9.6

1022

M
Index

dele te 916
journal event 275, 276
JSON streams
converting to IData objects 480
JSON strings
converting to IData objects 481
creating from documents 479
jsonStreamToDocument 480
jsonStringToDocument 481

key string lookup 864, 865

keys, obtaining a list in a data store 848

large flat file handling

iterator variable of convertToValues service 326
latch operations
checking latch s tatus 883
closing 882
opening 884
length
ofastring 864
list
adding, retrieving, or replacing elements 484
number of elements 487
registered consumer handlers 757
registered processors 772
registered provider handlers 758
universal names 939
list services 484, 484
listAdapterConnections 32
listAdapterListenerNotifications 40
listAdapterListeners 35
listAdapterPollingNotifications 41
listAdapterServices 46
listAll 940
listFFDictionaryEntries service 347
listFiles 310
listKeys 385, 674
listRegisteredA dapters 30
loadEnhancedXMLNode 973
loadPKCS7CertChain 680
loadXMLNode 983
locking a repository entry 849, 850, 853
locking considerations for pub.storage services 841
log off of FTP server 101, 139
logging

pipeline fields 375

login to FTP server 98
login to SFTP server 139
lookupDictionary 864
lookupTable 865
lowercase, converting to 873
ls 102, 140

makeString 866
mark 393
markSupported 394
Math folder 491
math services 492
max 500
mdelete 103
mergeHeaderAndBody 535
messageFormat 866
messageID 813
mget 104
MIME messages
adding body parts to 517
adding headers to 521
creating 523
creating encrypted messages 697
creating signed messages 700
decrypting 702
discovering content type 529
discovering number of parts 532
discovering subtype 534
generating message stream 529
getting content from 526
getting headers from 531
getting part headers from 527
getting top-level portion 533
merging HTTP response into InputStream 535
sending through SMTP 145
signing and encrypting 557, 698
verifying signed messages 703
MIME services 516
min 501
mkdir 141
modifySubscriber 278
moveFile 311
mput 104
multiple VCS users
removing 956
setting 957

webMethods Integration Server Built-In Services Reference Version 9.6

1023

M
Index

multiplyFloatList 501
multiplyFloats 502
multiplyIntList 503
multiplyInts 504
multiplyObjects 505

namespace components 657, 657, 657

native ID, retrieving 888
nerv
eventToDocument 282
node iterator
creating 970
freeXMLNode 968
getNextXMLNode 969
getXMLNodeIterator 970
notification error document type 591
notifying services 878
notifyPackageRelease 611
nu meric values
dividing 499
numeric values
adding 494, 495, 496, 497
dividing 500
multiplying 501, 502, 503, 504, 505
subtracting 506, 508
numericFormat 867

OAuth client 131

objects
adding 497
dividing 500
multiplying 505
subtracting 508
objectToString 868
obtaining information about 402
one-time tasks
adding to scheduler 626
updating to scheduler 642
one-way call, guaranteed 600
openLatch 884
outbound passwords 660
creating a WmSecureString 680
internal vs. public 672
listing keys 674
removing 674
retrieving 673

setting 671
updating 675
output templates 616

package management services 546

Package Release Registry
adding entries 605
deleting entries 606
obtaining local server list 609
package replication services 604
packageCreation 612
packages
activating 546
backing up 547
disabling 548
enabling 549
installing 549
recovering 551
reloading 552
padLeft 869
padRight 870
pattern strings, date patterns 176
pipeline
applying templates to 618
inserting Session object 359
removing fields 356
restoring previously saved 360, 361
saving contents to a file 364
saving into memory 363
tracing 375
using previously saved keys and values 362
validating against a document type 656
pipeline services 354
PKCS7 signatures 554
PKCS7 SignedData objects 554
creating 675
PKI profiles 554
portStatus specification 286
portStatusInfo document type 286
Pre-8.2 compatibility mode property 947
problemAction 813
problemHeaderQName 814
problemIRI 814
processCertsOnlyData 702
processEncryptedData 559, 702
processing
resuming for triggers 921

webMethods Integration Server Built-In Services Reference Version 9.6

1024

M
Index

suspending for triggers 928

processMessage 774
processRPCMessage 774
processSignedData 561, 703
protocols, retrieving inform ation a bout 375
protocols, retrieving informa tion about 359
pseudorandom number generator 505
pub
flow
setReponse2 368
pub.art
listRegisteredAdapters 30
pub.art.connection
disableConnection 31
enableConnection 31
getConnectionStatistics 32
queryConnectionState 33
pub.art.listener
disableListener 34
enableListener 35
queryListenerState 36
setListenerNodeConnection 37
pub.art.notification
disableListenerNotification 39
disablePollingNotification 39
enableListenerNotification 39
enablePollingNotification 40
lis tAdapterPollingNotifications 41
queryListenerNotificationState 42
queryPollingNotificationState 43
resumePollingNotification 44
setListenerNotificationNodeListener 44
setPollingNotificationNodeConnection 45
suspendPollingNotification 46
pub.art.service
listAdapterServices 46
setAdapterServiceNodeConnection 47
pub.art.transaction
commitTransaction 47
rollbackTransaction 48
setTransactionTimeout 49
startTransaction 50
pub.client
ftp 88, 89
http 110
smtp 145
soapClient 149
soapHTTP 166
soapRPC 170

pub.client.ftp
append 92
cd 92
cdls 93
delete 94
dir 94
get 95
login 98
logout 101, 139
ls 102, 140
mdele te 103
mget 104
mput 104, 105
put 105, 141
putCompletedNotification 107
quote 108
rename 108
sessioninfo 109
pub.client.oauth
executeRequest 131
pub.client.sftp
cd 135
chgrp 136
chmod 136
chown 137
get 137
login 139
mkdir 141
pwd 142
rename 143
rm 144
rmdir 144
symlink 145
pub.date
calculateDateDifference 181
currentNanoTime 182
dateBuild 182
dateTimeBuild 183
dateTimeFormat 185
elapsedNanoTime 186
formatDate 187
getCurrentDate 188
getCurrentDateString 188
getWorkingDays 189
pub.db
call 194
clearTransaction 196
close 197
closeAll 198

webMethods Integration Server Built-In Services Reference Version 9.6

1025

M
Index

commit 198
connect 199
delete 201
execSQL 203
getProcInfo 207
getProcs 208
getTableInfo 210
getTables 211
insert 213
query 215
rollback 216
startTransaction 217
update 218
pub.document
bytesToDocument 223
documentListToDocument 224
documentToBytes 226
documentToDocumentList 228
documentToXMLValues 230
XMLValuesToDocument 234
pub.e vent.eda
event 254
pub.event
addSubscriber 242
alarm 245
alarmInfo 246
audit 247
auditError 248
auditErrorInfo 250
auditInfo 251
callstack Item 252
deleteSubscriber 252
error 263
errorInfo 263
exception 264
exceptionInfo 266
gdEnd 267
gdEndInfo 268
gdStart 268
gdStartInfo 269
getEventTypes 270
getSubsc ribers 270
journal 275
journalInfo 276
modifySubscriber 278
portStatus 286
portStatusInfo 286
reloadEventManagerSettings 287
replication 287

replicationInfo 288
saveEventManagerSettings 289
security 289
securityInfo 291
sessionEnd 292
sessionEndInfo 293
sessionExpire 294
sessionExpireInfo 294
sessionStart 295
sessionStartInfo 296
stat 296
statInfo 298
tx End 300
tx EndInfo 300
txStart 301
txStartInfo 302
pub.event.eda
eventToDocument 255
schema_event 257
send 257
pub.event.nerv
eventToDocument 282
send 283
pub.file
bytesToFile 306
checkFileExistence 307
copyFile 307
deleteFile 308
getFile 309
listFiles 310
moveFile 311
readerToFile 312
streamToFile 313
stringToFile 314
pub.flatFile
convertToString 320
convertToValues 325
FormatService 331
getSupportedEncodings 334
pub.flatFile.generate
createDocumentType 335
createFFDictionary 335
deleteFFDictionary 336
deleteFFDictionaryEntry 337
deleteFFSchema 338
FFDictionary IS document type 338
FFSchema IS document type 341
findDependants 344
findReferences 344

webMethods Integration Server Built-In Services Reference Version 9.6

1026

M
Index

getFFDictionaryAsXML 345
getFFDictionaryEntryAsXML 346
getFFSchemaAsXML 346
listFFDictionaryEntries 347
saveXMLAsFFDictionary 348
saveXMLASFFSchema 349
updateFFDictionaryEntryFromXML 351
pub.flow
clearPipeline 356
debugLog 356
getLastError 357
getRetryCount 358, 905
getSession 359
getTransportInfo 359
invokeService 360
restorePipeline 361
restorePipelineFromFile 362
savePipeline 363
savePipelineToFile 364
setCustomContextID 365
setResponse 366
setResponseCode 370
setResponseHeader 370
setResponseHeaders 373
throwExceptionForRetry 374
tracePipeline 375
transportInfo 375
pub.hashtable
containsKey 384
createHashtable 385
get 385
listKeys 385
put 386
remove 386
size 387
pub.io
bytesToStream 391
close 392, 392
createByteArray 392, 392
mark 393
markSupported 394
read 395, 395
readAsString 395
readerToString 396
reset 397, 397
skip 397, 397
streamToBytes 398, 398
streamToReader 399
streamToString 399

stringToReader 400
stringToStream 400
pub.jms
documentResolverSpec 412
reply 421
send 429
pub.jms.wmjms
sendStream 474
pub.json
documentToJSONString 479
jsonStreamToDocument 480
jsonStringToDocument 481
pub.list
addItemToVector 484
appendToDocumentList 485
appendToStringList 486
sizeOfList 487
stringListToDocumentList 487
vectorToArray 488
pub.math
absoluteValue 494
addFloatList 494
addFloats 495
addIntList 496
addInts 497
addObjects 497
divideFloats 498
divideInts 499
divideObjects 500
max 500
min 501
multiplyFloatList 501
multiplyFloats 502
multiplyIntList 503
multiplyInts 504
multiplyObjects 505
randomDouble 505
roundNumber 506
subtractFloats 506
subtractInts 508
subtractObjects 508
toNumber 509
pub.mime
addBodyPart 517
addMimeHeader 521
createMimeData 523
getBodyPartContent 526
getBodyPartHeader 527
getContentType 529

webMethods Integration Server Built-In Services Reference Version 9.6

1027

M
Index

getEnvelopeStream 529
getMimeHeader 531
getNumParts 532
getPrimaryContentType 533
getSubContentType 534
mergeHeaderAndBody 535
pub.packages
backupPackage 547
disablePackage 548
enablePackage 549
installPackage 549
recoverPackage 551
reloadPackage 552
pub.pki.pkcs7
sign 554
verify 556
pub.pki.smime
createSignedAndEncryptedData 557
createSignedData 559
processEncryptedData 559
processSignedData 561
pub.publish
deliver 567
deliverAndWait 568
documentResolverSpec 571
envelope 573
getRedeliveryCount 578
publish 580
publishAndWait 582
reply 586
syncDocuments 588
waitForReply 589, 589
pub.publish.notification
error 591
pub.remote
invoke 595
pub.remote.gd
end 597
getStatus 597
invoke 598
restart 599
retrieve 599
send 600
start 600
submit 601
pub.replicator
addReleaseRegistryEntry 605
deleteReleaseRegistryEntry 606
distributeViaFTP 607

distributeViaSvcPull 608
distributeViaSvcPush 609
generateReplicationEvent 609
getLocalReleasedList 609
getRemoteReleasedList 610
notifyPackageRelease 611
packageCreation 612
pub.report
runFileTemplate 616
runFileTemplateOnPipe 617
runStringTemplate 617
runStringTemplateOnPipe 618
runTemplate 618
runTemplateOnPipe 619
pub.scheduler
addComplexTask 623
addOnetimeTask 626
addRepeatingTask 628
cancelTask 631
getTaskIDs 631
getTaskInfo 632
getUserTaskList 636
migrateTasksToJDBC 636
resumeTask 637
suspendTask 638
updateComplexTask 639
updateOneTimeTask 642
updateRepeatingTask 644
pub.schema
createXSD 651
validate 653
validatePipeline 656
pub.schema.w3c 657
datatypes 657
structures 657
xml 657
xsi 657
pub.security
clearKeyAndChain 663
setKeyAndChain 664
setKeyAndChainFromBytes 665
pub.security.enterpriseGateway
alertSpec 666
pub.security.keystore
getCertificate 668
getKeyAndChain 669, 669
getTrustedCertificates 669
setKeyAndChain 670
pub.security.keystore.pkcs7

webMethods Integration Server Built-In Services Reference Version 9.6

1028

M
Index

sign 670
pub.security.outboundPasswords
listKeys 674
removePassword 674
setPassword 671
updatePassword 675
pub.security.pkcs7
sign 675
verify 677
pub.security.util
convertSecureString 681
createMessageDigest 678
createSecureString 680
destroySecureString 682
getCertificateInfo 679
loadPKCS7CertChain 680
pub.smime
createCertsOnlyData 697
createEncryptedData 697
createSignedAndEncryptedData 698
createSignedData 700
processCertsOnlyData 702
processEncryptedData 702
processSignedData 703
pub.smime.keystore
createSignedAndEncryptedData 706
createSignedData 708
processEncryptedData 708
pub.soa p.wsa
to 817
pub.soap.ha ndler
registerConsumer 762
pub.soap.handler
addBodyBlock 721
addFau ltBlock 724
addHeaderBlock 726
generateDocumentTypesFromWSDL 733
getBodyBlock 735
getBodyBlockQNames 737
getFaultBlock 738
getInitialSOAPRequest 746
getMessageAddressingProperties 747
getServicePipeline 750
getWebServiceInvocationProperties 753
hasFaultMessage 756
listConsumer 757
listProvider 758
registerConsumer 730, 743, 749, 752, 755, 759,
760, 766, 767, 768, 769

registerProvider 760
removeBodyBlock 763
removeHeaderBlock 764
unregis terCons umer 769
unregisterProvider 770
updateFaultBlock 770
pub.soap.processor
list 772
processMessage 774
processRPCMessage 774
registerProcessor 775
unregisterProcessor 776
pub.soap.schema
encoding 777
encoding_1_2 777
envelope 777
envelope_1_2 777
pub.soap.ut ils
stringToSoapData 808
pub.soap.utils
addBodyEnt ry 777
addHeaderEntry 779
addTrailer 781
createSoapData 787
exitUnabl eToUnderstand 789
getActor 790
getBody 791
getBodyEntries 791
getDocument 792
getEncoding 793
getHeader 793
getHeaderEntries 794
getMustUnderstand 795
getQName 796
getTrailer 797
QName 799
removeBodyEntry 800
removeHeaderEntry 801
removeTrailer 802
requestResponseSpec 803
soapDataToBytes 805
soapDataToString 805
streamToSoapD ata 807
validateSoapData 809
pub.soap.wsa
action 810
faultTo 810
from 812
messageID 813

webMethods Integration Server Built-In Services Reference Version 9.6

1029

M
Index

problemAction 813
problemHeaderQName 814
problemIRI 814
relatesTo 815
replyTo 816
retryAfter 817
schema_wsa 818
pub.soap.wsa.submission
act ion 818
faultTo 819
from 821
messageID 822
relatesTo 823
replyTo 824
retryAfter 826
schema_wsa_submission 827
to 826
pub.soap.wsrm
closeSequ ence 827
createSequence 828
sendAcknowledgementRequest 833
waitUntilSequenceCompleted 836
pub.storage
add 845
checkpoint restart example 843
closeStore 846
data store locking 841
deleteStore 846
entry locking 841
get 847
keys 848
listLocks 849
lock 850
lock duration 842
lock wait time 842
put 852
registerStore 853
releaseLocks 853
remove 854
short-term store 840
unlock 855
pub.string
base64Decode 860
base64Encode 860
bytesToString 861
concat 861
HTMLDecode 862
HTMLEncode 862
indexOf 863

length 864
lookupDictionary 864
lookupTable 865
makeString 866
messageFormat 866
numericFormat 867
objectToString 868
padLeft 869
padRight 870
replace 871
stringToBytes 871
substring 872
tokenize 872
toLower 873
toUpper 873
trim 874
URLDecode 874
URLEncode 875
pub.sync
notify 878
shutdown 879
wait 879
pub.synchronization.latch
closeLatch 882
isLatchClosed 883
openLatch 884
pub.synchronization.xref
createXReference 885
deleteByObjectId 886
deleteXReference 886
getCanonicalKey 887
getNativeId 888
insertXReference 889
pub.trigger
createJMSTrigger 893
createTrigger 907
deleteJMSTrigger 916
resumeProcessing 921
resumeRetrieval 924
suspendProcessing 928
suspendRetrieval 930
pub.universalName
find 938
list 939
listAll 940
pub.utils
deepClone 944
executeOSCommand 945
generateUUID 947

webMethods Integration Server Built-In Services Reference Version 9.6

1030

M
Index

getServerProperty
retrieves value of a server property 947
pub.utils.ws
setCompatibilityModeFalse 947
pub.vcs.admin
getUsers 954
removeCurrentUser 955
removeMultipleUsers 956
setCurrentUser 956
setMultipleUsers 957
pub.xml
documentToXMLString 961
freeXMLNode 968
getNextXMLNode 969
getXMLNodeIterator 970
getXMLNodeType 973
loadEnhancedXMLNode 973
loadXMLNode 983
queryXMLNode 991
xmlNodeToDocument 994
xmlStringToEnhancedXMLNode 1004
xmlStringToXMLNode 1008
pub.xslt.Transformations
transformSerialXML 1012
publish service 580
publish/subscribe, latching and cross-referencing
operations 882
publishAndWait service 582
publishing packages 604
addReleaseRegistryEntry 605
deleteReleaseRegistryEntry 606
distributeViaFTP 607
distributeViaSvcPull 608
distributeViaSvcPush 609
generateReplicationEvent 609
getLocalReleasedList 609
getRemoteReleasedList 610
notifyPackageRelease 611
packageCreation 612
put 386
put (FTP) files 105
put (SFTP) files 141

QName document type 799

queryConnectionState 33
querying a database 215
queryListenerNotificationState 42

queryListenerState 36
queryPollingNotificationState 43
queryXMLNode 991
quote 108

random number generator 505

randomDouble 505
raw offset for time zones 177
read 395
readAsString 395
readerToFile 312
readerToString 396
records, deleting particular type 886
recoverPackage 551
recurring tasks, adding to scheduler 628
redelivery count, retrieving for documents 578
registering
consum er handlers 749
consumer handlers 730, 743, 752, 755, 759,
760, 762, 766, 767, 768, 769
providerhandlers 760
unregistering consumer handlers 769
unregistering provider handlers 770
registering data stores 853
registerProcessor 775
registerStore 853
relatesTo 815
release registry. 605
reloadEventManagerSettings 287
reloadPackage 552
remote file, appending data to 92
remote procedure call, submitting 170
remote servers, invoking services on 594, 595
remove 386
removeBodyBlock 763
removeBodyEntry 800
removeCurrentUser 955
removeHeaderBlock 764
removeHeaderEntry 801
removeMultipleUsers 956
removeTrailer 802
removing entries from data stores 854
renaming files on an FTP server 108
renaming files on an SFTP server 143
repeating tasks, updating to scheduler 644
replacing strings 871
replication specification 287

webMethods Integration Server Built-In Services Reference Version 9.6

1031

M
Index

replicationInfo document type 288

replicator services 604
reply documents
for join conditions 587
retrieving for asynchronous request 589
sending 586
reply service 586
replyTo 816
report services 616
repository
closing data store 846
creating/opening 853
deleting data store 846
inserting entries 845
inserting/updating entries 852
list of keys in 848
locking entries 849, 850, 853
registering 853
removing entries 854
retrieving keys from 848
retrieving values from 847
unlocking entries 855
request/reply model
deliverAndWait service 570
delivering a request 568
multiple reply documents 585
publishAndWait service 585
publishing request 582
publishing request to a specific client 568
retrieving reply 589
sending replies 586
waitForReply service 589
waiting for reply 584
requestResponseSpec 803
reset 397
response string, forcing 366
restarting a guaranteed delivery transaction 599
restorePipeline 361
restorePipelineFromFile 362
resumeListener 37
resumePollingNotification 44
resumeTask 636, 636, 637
resuming
document processing for triggers 921
document retrieval for triggers 924
retrieval
resuming for triggers 924
suspending for triggers 930
retrieving

documents from a local file system 304, 384

files from FTP server 95
files from SFTP server 137
MIME content 526
MIME message headers 527, 531
results of guaranteed delivery transaction 599
retrieving reply 589
retry count, retrieving 358
retry exception 374
retry limit
setting to zero 905
retryAfter 817
rm 144
rmdir 144
rollback 216
rollbackTransaction 48
roundNumber 506
RPC, submitting 170
runFileTemplate 616
runFileTemplateOnPipe 617
runStringTemplate 617
runStringTemplateOnPipe 618
runTemplate 618
runTemplateOnPipe 619

S/MIME messages
creating certs-only message 697
creating encrypted messages 697
creating signed messages 700
creating using PKI profiles 554
decrypting 559, 702
extracting certificates from certs-only message
702
verifying signed messages 561, 703
S/MIME services 696
saveEventManagerSettings 289
savePipeline 363
savePipelineToFile 364
saveXML AsFFDictionary service 348
saveXMLASFFSchema service 349
sc hemas
schema_ws a_submission 827
scheduler
adding complex tasks 623
adding one-time tasks 626
canceling tasks 631
recurring tasks 628

webMethods Integration Server Built-In Services Reference Version 9.6

1032

M
Index

resuming tasks 637

retrieving list of task IDs 631
retrieving task info 632
suspending tasks 638
updating complex tasks 639
updating one-time tasks 642
updating repeating tasks 644
scheduler services 622
schema
for events 257
schema domain 654
schema services 650
schemas
components 657
creating 651
datatypes 657
for validating 653
namespace components 657, 657
retrieving tables 211
SOAP encod ing schema, version 1.2 777
SOAP encoding schema 777
SOAP envelope schema 777
SOAP envelope schema, version 1.2 777
wsa 818
XML datatypes 657
sending a guaranteed call 600
sending STOR or STOU commands to remove
server 89, 105, 106
sendStream 474
server log
pipeline field na mes and values 375
writing to 356
services
default access permissions 24
listing of 21
Session object, inserting in pipeline 359
sessionEnd specification 292
sessionEndInfo document type 293
sessionEx pireInfo document type 294
sessionExpire specification 294
sessioninfo 109
sessionStart specification 295
sessionStartInfo document type 296
setAdapterServiceNodeConnection 47
setCurrentUser 956
setCustomContextID 365
setKeyAndChain 664, 665
setListenerNodeConnection 37
setListenerNotificationNodeListener 44

setMultipleUsers 957
setPollingNotificationNodeConnection 45
setResponse 366
setResponse2 368
setResponseCode 370
setResponseHeader 370
setResponseHeaders 373
setTransactionTimeout 49
SFTP
changing file owner 137
changing owner group 136
changingpermissions 136
file transfer 141
login 139
re move files 144
remove directory 144
renaming files 143
retrieving files 137
symbolic link between files 145
transferring files 141
view remote working directory 142
sftp working directory, changing 135
short-term store 840
shutdown service 879
signed data object, creating 675
SignedData objects 554
signing and encrypting MIME messages 557
signing MIME messages 559, 700, 703
size 387
sizeOfList 487
skip 397
SMTP servers, submitting requests to 110
SMTP, sending MIME messages 145
SOAP
actor attribute 790
adding body entries 777
adding header entries 779
converting SOAP object to Byte Array 805
converting SOAP object to String 805
converting stre am to SOAP object 807
converting string to SOAP object 808
creating SOAP objects 787
en coding schema, ve rsion 1.2 777
encoding schema 777
envelope schema 777
envelope schema, version 1.2 777
executing the default processor 774
executing the default RPC processor 774
getting body entries 791, 791, 797

webMethods Integration Server Built-In Services Reference Version 9.6

1033

M
Index

getting encoding entries 793

getting entire message 792
getting header entries 794
getting QNames 796
listing handlers, consumer 757
listing handlers, provider 758
listing processors 772
mustUnderstand attribute 789, 795
registering a proces sor 775
registering handlers, consumer 730, 743, 749,
752, 755, 759, 760, 762, 766, 767, 768, 769
registering handlers, provider 760
removing body entries 800
removing header entries 801
removing trailers 802
sending a SOAP message 166
sending a SOAP message over HTTP 149
specification for custom processor 803
specificationfor target service 803
submitting an RPC request 170
unregistering handlers, consumer 769
unregistering handlers, provider 770
unregistering processors 776
updating Fault Code and Fault String 770
validating SOAP obj ects 809
WS-A ddress ing wsa
faul tTo 810
WS-Addres sing wsa
from 812
WS-Addressing wsa
action 810
message ID 813
problemAction 813
problemHea derQN ame 814
problemIRI 814
relatesTo 815
replyTo 816
retryAfter 817
to 817
WS-Addressing wsa.submission
action 818
faultTo 819
from 821
message ID 822
relatesTo 823
replyTo 824
retryAft er 826
to 826
SOAP messages, inserting trailer 781

SOAP services 712

soapClient 149
soapDataToBytes 805
soapDataToString 805
soapHTTP 166
soapRPC 170
special characters
handling in XML strings 964
specification
audit error event 248
specifications
alarm event handler 245
audit event handler 247
exception event handler 264
gdEnd 267
gdStart 268
portStatus event handler 286
replication event handler 287
sessionEnd event handler 292
sessionExpire event handler 294
sessionStart event handler 295
stat event handler 296
txEnd event handler 300
txStart event handler 301
SQL statements, executing 203
starting a guaranteed delivery transaction 600
startTransaction 50, 217
stat specification 296
statInfo document type 298
status of guaranteed delivery transactions 597
STOR or STOU commands, sending to remote
server
using pub.client
ftp service 89
using pub.client.ftp
mput service 105
put service 106
storage services 840, 840
stored procedures
invoking 194
retrieving information about 207
retrieving names of 208
streamToBytes 398, 398
streamToFile 313
streamToReader 399
streamToSoapData 807
streamToString 399
string array, formatting 866
stringListToDocumentList 487

webMethods Integration Server Built-In Services Reference Version 9.6

1034

M
Index

strings
adding to list 486
base64 decoding 860
base64 encoding 860
byte array conversion 861
concatenating 861
concatenating an array of strings 866
converted from documents 230
converting list to document list 487
converting to byte array 871
converting to lower case 873
converting to uppercase 873
decoding URL-encoded 874
HTML to native characters 862
length of 864
native characters to HTML 862
padding beginning 869
padding end 870
replacing all 871
returning substring of 872
tokenizing into an array 872
transformation services 858
trimming white space 874
URL-encoding 875
XML values to a document 234
stringToBytes 871
stringToFile 314
stringToReader 400
stringToSoapData 808
stringToStream 400
submis sion action 818
submission
faultTo 819
from 821
messageID 822
relatesTo 823
replyTo 824
retryAfter 826
to 826
submitting an asynchronous call to a remote server
601
subscribing to packages 604
subscriptions, creating 242
substring 872
indexing first occurrence 863
subtractFloats 506
subtractInts 508
subtractObjects 508
subtype, getting from MIME message 534

sum of numeric values 494, 495, 496, 497

suspended tasks, resuming 637
suspending
document processing for triggers 928
document retrieval for triggers 930
suspendListener 38
suspendPollingNotification 46
suspendTask 638
symlink 145
Synchronization folder 881
synchronization services
coordinating the execution of services 878
performing latching and cross-referencing
operations 882
synchronous call to a remote server 598
synchronous request/r eply
delivering a re quest 569
synchronous request/reply
description of 570, 585
publishing a request 584
syncToBroker 588

tables
inserting rows 213
removing rows 201
retrieving column information 210
retrieving names of 211
retrieving rows from 215
updating all rows 218
tasks
adding complex to scheduler 623
adding one-time to scheduler 626
adding recurring to scheduler 628
migrating to external database 636
obtaining information about 632
obtaining list of 636
removing from scheduler 631
resuming 637
retrieving IDs for 631
suspending 638
updating complex to scheduler 639
updating one-time to scheduler 642
updating repeating to scheduler 644
templates
applying to a document 616
applying to pipeline 617, 618
from string objects 617

webMethods Integration Server Built-In Services Reference Version 9.6

1035

M
Index

time zones 177

time, converting formats 185
to 817
tokenizing a string 872
toLower 873
toNumber 509
toUpper 873
tracePipeline 375
trailers, adding to SOAP messages 781
transactional state, clearing 196
transactions, ending guaranteed delivery 597
transforming XML 1012
transient error, description of 374
transportInfo 375
Trigger folder 891
trigger services
performance 905
retry count 358
retry count, retrieving 905
retrying 374
triggers
creating JMS 893
deleting JMS 916
management services 892
resuming document processing 921
resuming document retrieval 924
retry, setting to 0 905
suspending document retrieval 930
suspending processing 928
trimming white space 874
txEnd specification 300
txEndInfo docum ent type 300
txStart specification 301
txStartInfodocument type 302

universal name services 938

universal names
finding service names for 938
listing the registry 939
unlocking entries in data stores 855
unregisterProcessor 776
unsubscribing from an event 252
updateComplexTask 639
updateFFDictionaryEntryFromXML service 351
updateOneTimeTask 642
updateRepeatingTask 644
updating

rows in a data base table 218

uppercase, converting to 873
URLDecode 874
URLEncode 875
user management, VCS 954
get user names 954
remove current user 955
remove multiple users 956
set current user 956
set multiple users 957
Utils services
retrieves value of server property 944

validatePipeline 656
validateSoapData 809
validating an object 653
VCS folder 953
VCS Integration feature 954
getting users 954
remove current user 955
remove multiple users 956
set current user 956
set multiple users 957
vectorToArray 488
verifying digital signatures 677
verifying signed data objects 556

waitForReply service 589

waiting for delivery from a notifying service 879
watt.security.ope.AllowInternalPasswordAccess
672
Web service de scriptor
consumer
registering the handler 767
Web service descriptor
con sumer
registering the handler 759
consumer
registering the handler 730, 743, 749, 752,
755, 760, 762, 766, 768, 769
unregistering the handler 769
Pre-8.2 compatibility mode property 947
provider
registering the handler 760
unregistering the handler 770
white space, trimming 874

webMethods Integration Server Built-In Services Reference Version 9.6

1036

M
Index

WmSecureString 680
converting 681
creating 680
destroying 682
working directory, changing 92
wsrm
closeSequence 827
createSequence 828
sendAcknowledgementRequest 833
waitUntilSequenceCompleted 836

XML
datatypes 657
pub.schema.w3c 657, 657
XML documents
conv erting to IData objects 994
converting to XML nodes 1004, 1008
XML nodes
creating from XML string 1004, 1008
extracting data from 991
freeing 968
getting type info 973
loading from URL 973, 983
querying 991
XML schemas
components 657
datatypes 657
XML services 960
XML strings
creating from documents 961
XML strings, creating from documents
handling special characters 964
XML values
converting from a document 230
xmlNodeToDocument 994
xmlStringToEnhancedXMLNode 1004
xmlStringToXMLNode 1008
XMLValuesToDocument 234
XQL queries 991
XSLT folder 1011
XSLT services
maintaining the stylesheet cache 1012
transforming an XML stream 1012

webMethods Integration Server Built-In Services Reference Version 9.6

1037