IBM Workload Automation: Scheduling Applications with IBM

IBM Workload AutomationVersion 9 Release 4

Scheduling Applications with IBMWorkload Automation

IBM

NoteBefore using this information and the product it supports, read the information in Notices on page 347.

This edition applies to version 9, release 4, modification level 0 of IBM Workload Scheduler (program number5698-WSH) and to all subsequent releases and modifications until otherwise indicated in new editions.

Copyright IBM Corporation 2001, 2016. Copyright HCL Technologies Limited 2016, 2017

Contents

Figures . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . ix

About this Publication . . . . . . . . xiWhat is new in this release . . . . . . . . . xiWho should read this publication . . . . . . . xiAccessibility . . . . . . . . . . . . . . xiiTechnical training . . . . . . . . . . . . xiiSupport information . . . . . . . . . . . xiiHow to read syntax diagrams . . . . . . . . xii

Part 1. Overview . . . . . . . . . . 1

Chapter 1. Supported agentworkstations. . . . . . . . . . . . . 3

Part 2. Job plug-ins to extendworkload scheduling capabilities . . 5

Chapter 2. Defining a job . . . . . . . 7

Chapter 3. Scheduling and submittingjobs and job streams . . . . . . . . . 9

Chapter 4. Monitoring IBM WorkloadScheduler jobs . . . . . . . . . . . 11

Chapter 5. Analyzing the job log. . . . 13

Chapter 6. IBM BigInsights jobs . . . . 15

Chapter 7. IBM Cloudant jobs . . . . . 19

Chapter 8. IBM Cognos jobs . . . . . 23Business scenario . . . . . . . . . . . . 23Defining an IBM Workload Scheduler job to run anIBM Cognos report . . . . . . . . . . . . 23

Defining jobs by using the Dynamic WorkloadConsole. . . . . . . . . . . . . . . 24Job definition for IBM Cognos reports . . . . 25Specifying the parameter format for date, time,and time stamp . . . . . . . . . . . . 31Specifying parameterized filters . . . . . . 31

Scheduling and submitting job streams for IBMCognos reports . . . . . . . . . . . . . 33Customizing IBM Workload Scheduler to run IBMCognos reports . . . . . . . . . . . . . 33Configuring the agent to use Cognos in SSL . . . 34Mapping between job statuses and IBM Cognosreport statuses . . . . . . . . . . . . . 36

Job log output . . . . . . . . . . . . . 37

Chapter 9. IBM InfoSphere DataStagejobs . . . . . . . . . . . . . . . . 41Business scenario . . . . . . . . . . . . 41Defining an IBM Workload Scheduler job to run anInfoSphere DataStage job . . . . . . . . . . 41

Job definition for IBM InfoSphere DataStage jobs 42Defining IBM Workload Scheduler jobs to runIBM InfoSphere DataStage jobs by using theDynamic Workload Console . . . . . . . . 45

Scheduling and submitting job streams for IBMInfoSphere DataStage jobs . . . . . . . . . 47Customizing IBM Workload Scheduler to run IBMInfoSphere DataStage jobs . . . . . . . . . 47Mapping between IBM Workload Scheduler andIBM InfoSphere DataStage job statuses . . . . . 48Job log output . . . . . . . . . . . . . 49Analyzing the InfoSphere DataStage job properties 50

Chapter 10. IBM SterlingConnect:Direct jobs . . . . . . . . . 53Business scenario . . . . . . . . . . . . 62

Scenario goal . . . . . . . . . . . . . 62

Chapter 11. IBM WebSphere MQ jobs 63Business scenario . . . . . . . . . . . . 67

Scenario goal . . . . . . . . . . . . . 67

Chapter 12. Hadoop Distributed FileSystem jobs . . . . . . . . . . . . 69

Chapter 13. Hadoop Map Reduce jobs 73

Chapter 14. Apache Oozie jobs . . . . 77

Chapter 15. Informatica PowerCenterjobs . . . . . . . . . . . . . . . . 81Defining an IBM Workload Scheduler InformaticaPowerCenter job to schedule workflows . . . . . 82

PowerCenter job definition . . . . . . . . 82Defining IBM Workload Scheduler jobs toschedule Informatica PowerCenter workflowswith the Dynamic Workload Console . . . . . 84

Customizing IBM Workload Scheduler to runInformatica PowerCenter jobs . . . . . . . . 87Configuring the agent for SSL . . . . . . . . 88Scheduling and submitting job streams forPowerCenter jobs . . . . . . . . . . . . 89Monitoring IBM Workload Scheduler jobs that runInformatica PowerCenter workflows . . . . . . 89

Procedure for restarting an InformaticaPowerCenter workflow from the failed task . . 91

iii

||

||

|||||||

||||||

|||

||

Mapping PowerCenter workflow status to jobstatus . . . . . . . . . . . . . . . 92

Known problems and workarounds . . . . . . 92Incorrect worklet status displayed in the job log 92Cannot submit jobs after a Web Services Hubrestart . . . . . . . . . . . . . . . 93

Chapter 16. Oracle E-Business Suitejobs . . . . . . . . . . . . . . . . 95Business scenario . . . . . . . . . . . . 95Defining an IBM Workload Scheduler job toschedule Oracle E-Business Suite applications . . . 96

Job definition for Oracle E-Business Suite jobs . . 96Defining IBM Workload Scheduler jobs to runOracle E-Business Suite jobs by using theDynamic Workload Console . . . . . . . . 98Scheduling and submitting job streams for OracleE-Business Suite jobs . . . . . . . . . . 99Customizing IBM Workload Scheduler to runOracle E-Business Suite jobs . . . . . . . . 99Mapping between IBM Workload Scheduler jobstatuses and Oracle E-Business Suite applicationstatuses . . . . . . . . . . . . . . 101Job log output . . . . . . . . . . . . 101Analyzing the Oracle E-Business Suite jobproperties . . . . . . . . . . . . . 102

Chapter 17. Salesforce jobs . . . . . 103

Part 3. Access methods . . . . . . 111

Chapter 18. Installing and configuringthe access methods . . . . . . . . 113Setting options for the access methods . . . . . 113

Option value inheritance . . . . . . . . 116Editing the options files from the DynamicWorkload Console . . . . . . . . . . . 116Using the Option Editor . . . . . . . . . 117

Defining supported agent workstations. . . . . 120Creating a workstation using the DynamicWorkload Console . . . . . . . . . . . 120Creating a workstation using the command line 121Defining workstations for end-to-end scheduling 122

Defining jobs for supported agents . . . . . . 124Defining jobs with the Dynamic WorkloadConsole . . . . . . . . . . . . . . 125Defining jobs using the command line . . . . 125Defining jobs for end-to-end scheduling . . . 126

Submitting jobs. . . . . . . . . . . . . 127

Chapter 19. Access method forPeopleSoft . . . . . . . . . . . . 129Features . . . . . . . . . . . . . . . 129Roles and responsibilities . . . . . . . . . 129Scheduling process for the PeopleSoft supportedagents . . . . . . . . . . . . . . . . 130PeopleSoft job tracking in IBM Workload Scheduler 130Security . . . . . . . . . . . . . . . 130Configuring the PeopleSoft access method. . . . 130

Defining the configuration options . . . . . 130Creating a batch processing ID in PeopleSoft 133Configuring the ITWS_PSXA PeopleSoft project 134Uploading the PeopleSoft project . . . . . . 134

Defining PeopleSoft jobs. . . . . . . . . . 136Defining PeopleSoft jobs in IBM WorkloadScheduler. . . . . . . . . . . . . . 137Configuring the job status mapping policy . . 139

Chapter 20. Access method for z/OS 141Features . . . . . . . . . . . . . . . 141Roles and responsibilities . . . . . . . . . 141Installing, configuring, and uninstalling the z/OSgateway . . . . . . . . . . . . . . . 142

Installing . . . . . . . . . . . . . . 142Configuring . . . . . . . . . . . . . 144Uninstalling . . . . . . . . . . . . . 145

Additional information . . . . . . . . . . 145Gateway software components . . . . . . 145IEFU84 Exit . . . . . . . . . . . . . 146Security . . . . . . . . . . . . . . 146Startup . . . . . . . . . . . . . . 146SYSTSIN variables. . . . . . . . . . . 146z/OS gateway version . . . . . . . . . 149

Downloading z/OS gateway fixes from FTP . . . 149Locating product support . . . . . . . . . 151Configuring the z/OS access method . . . . . 152

Defining the configuration options . . . . . 152Defining jobs in z/OS . . . . . . . . . 153Defining z/OS jobs in IBM Workload Scheduler 153

Reference information . . . . . . . . . . 157Technical overview . . . . . . . . . . 157Diagnostic information . . . . . . . . . 161Troubleshooting . . . . . . . . . . . 161

Chapter 21. Common serviceability forthe access methods . . . . . . . . 165The return code mapping feature . . . . . . . 165

Parameters . . . . . . . . . . . . . 165Creating a return code mapping file . . . . . 165Return code mapping for psagent . . . . . 167Return code mapping for r3batch. . . . . . 167

Configuring the tracing utility . . . . . . . . 170Customizing the .properties file . . . . . . 170Configuration file example for the SAP accessmethod . . . . . . . . . . . . . . 172

Part 4. Integration with SAP . . . . 173

Chapter 22. Introducing IBM WorkloadScheduler for SAP . . . . . . . . . 175Features . . . . . . . . . . . . . . . 176

Chapter 23. Access method for SAP 179Scheduling process for the agent workstationhosting the r3batch access method . . . . . . 179Roles and responsibilities . . . . . . . . . 180Configuring user authorization (Security file). . . 181Configuring the SAP R/3 environment . . . . . 182

iv IBM Workload Automation: Scheduling Applications with IBM Workload Automation

||

Overview. . . . . . . . . . . . . . 182Creating the IBM Workload Scheduler RFC user 182Creating the authorization profile for the IBMWorkload Scheduler user . . . . . . . . 183Copying the correction and transport files . . . 185Importing ABAP/4 function modules into SAPR/3 . . . . . . . . . . . . . . . 186Changing the IBM Workload Scheduler RFCuser ID password . . . . . . . . . . . 189Securing data communication . . . . . . . 190Print parameter and job class issues . . . . . 191Unicode support . . . . . . . . . . . 191Migrating from previous versions . . . . . 193

Configuring the SAP R/3 access method . . . . 193Defining the configuration options . . . . . 195Configuration options usage . . . . . . . 205Connecting to the SAP system. . . . . . . 206Configuring SAP event monitoring . . . . . 208

Defining SAP jobs . . . . . . . . . . . . 209Creating SAP Standard R/3 jobs from theDynamic Workload Console . . . . . . . 210Setting the SAP data connection . . . . . . 214Managing SAP variants using the DynamicWorkload Console . . . . . . . . . . . 214Editing a standard SAP job . . . . . . . . 217Task string to define SAP jobs . . . . . . . 218

Managing SAP jobs . . . . . . . . . . . 226Displaying details about a standard SAP job . . 226Verifying the status of a standard SAP job . . . 227Deleting a standard SAP job from the SAPdatabase . . . . . . . . . . . . . . 227Balancing SAP workload using server groups 228Mapping between IBM Workload Scheduler andSAP job states . . . . . . . . . . . . 228Managing spools . . . . . . . . . . . 229Killing an SAP job instance . . . . . . . . 230Raising an SAP event. . . . . . . . . . 230Rerunning a standard SAP job. . . . . . . 232

Defining SAP jobs dynamically . . . . . . . 234Task string to define SAP jobs dynamically . . 234Specifying job parameters using variablesubstitution . . . . . . . . . . . . . 247Examples: Dynamically defining and updatingSAP jobs . . . . . . . . . . . . . . 247

Defining conditions and criteria . . . . . . . 248Example: Defining which raised events to log 250

Using the BDC Wait option. . . . . . . . . 252Job interception and parent-child features . . . . 253

Implementing job interception . . . . . . . 253The parent-child feature . . . . . . . . . 261

Using Business Information Warehouse. . . . . 262Business Warehouse components . . . . . . 262Defining user authorizations to manage SAPR/3 Business Warehouse InfoPackages andprocess chains . . . . . . . . . . . . 262Managing SAP R/3 Business WarehouseInfoPackages and process chains . . . . . . 263

Job throttling feature . . . . . . . . . . . 276Business scenario . . . . . . . . . . . 276Software prerequisites . . . . . . . . . 277Setting and using job throttling . . . . . . 277

Sending data from job throttling to the CCMSMonitoring Architecture . . . . . . . . . 280

Exporting SAP R/3 factory calendars . . . . . 281Business scenario . . . . . . . . . . . 281Exporting and importing SAP R/3 factorycalendars . . . . . . . . . . . . . . 281

Defining internetwork dependencies and eventrules based on SAP R/3 background events . . . 284

Defining internetwork dependencies based onSAP background events . . . . . . . . . 284Defining internetwork dependencies based onSAP background events with the DynamicWorkload Console . . . . . . . . . . . 288Defining event rules based on SAP backgroundevents . . . . . . . . . . . . . . . 288Setting a filter for SAP background events in thesecurity file . . . . . . . . . . . . . 291

Defining event rules based on IDoc records . . . 292Business scenario . . . . . . . . . . . 292Creating event rules based on IDocs. . . . . 293Examples of event rules based on IDocs . . . 298

Defining event rules based on CCMS MonitoringArchitecture alerts . . . . . . . . . . . . 300

Business scenarios . . . . . . . . . . . 300Creating event rules based on CCMS alerts . . 301Getting alert status and committing alerts by anexternal task. . . . . . . . . . . . . 307Example of an event rule based on CCMS alerts 309

National Language support. . . . . . . . . 310Setting National Language support options . . 311SAP R/3 supported code pages . . . . . . 311

Troubleshooting . . . . . . . . . . . . 312Troubleshooting the SAP R/3 connection . . . 312Other known problems . . . . . . . . . 313

Chapter 24. SAP job plug-ins toextend workload schedulingcapabilities . . . . . . . . . . . . 323SAP Process Integration (PI) Channel jobs . . . . 323

Business scenario . . . . . . . . . . . 323Prerequisites. . . . . . . . . . . . . 324Defining an IBM Workload Scheduler job thatruns an SAP PI Channel job . . . . . . . 325Submitting IBM Workload Scheduler job streamsfor SAP PI Channel jobs . . . . . . . . . 327Mapping between IBM Workload Scheduler andSAP PI Channel job statuses . . . . . . . 327Job log output . . . . . . . . . . . . 327

SAP BusinessObjects BI jobs . . . . . . . . 328

Chapter 25. Scheduling jobs on IBMWorkload Scheduler from SAPSolution Manager . . . . . . . . . 337Registering the master domain manager on SAPSolution Manager . . . . . . . . . . . . 337Scheduling . . . . . . . . . . . . . . 340

Scheduling jobs directly . . . . . . . . . 340Scheduling from job documentation . . . . . 341

Monitoring . . . . . . . . . . . . . . 342

Contents v

|||||||||||||||

Setting up to log traces on WebSphere ApplicationServer . . . . . . . . . . . . . . . . 343

Part 5. Appendixes . . . . . . . . 345

Notices . . . . . . . . . . . . . . 347Trademarks . . . . . . . . . . . . . . 349Terms and conditions for product documentation 349Notices and information. . . . . . . . . . 350Libmsg . . . . . . . . . . . . . . . 351

Apache Jakarta ORO . . . . . . . . . . . 351ISMP Installer (InstallShield 10.50x) . . . . . . 352JXML CODE. . . . . . . . . . . . . . 352InfoZip CODE . . . . . . . . . . . . . 353HSQL Code . . . . . . . . . . . . . . 354HP-UX Runtime Environment, for the Java 2Platform . . . . . . . . . . . . . . . 355

Index . . . . . . . . . . . . . . . 359

vi IBM Workload Automation: Scheduling Applications with IBM Workload Automation

|||

Figures

1. The Option Editor . . . . . . . . . . 1182. Defining an Extended Agent workstation 1243. Defining an Extended Agent job for

end-to-end scheduling . . . . . . . . 1274. The Variant List panel . . . . . . . . 2155. The Variant Information page of the Variant

List panel . . . . . . . . . . . . . 2166. The Raise Event panel . . . . . . . . 2317. The Table Criteria panel . . . . . . . . 257

8. The Table Criteria panel . . . . . . . . 2609. Dynamic Workload Console - Table of results 269

10. Dynamic Workload Console - Details of aprocess chain job . . . . . . . . . . 270

11. Managing high priority IDocs overview 29312. A monitor and its MTEs - SAP AG 2009.

All rights reserved. . . . . . . . . . 30213. Name and description of an MTE - SAP

AG 2009. All rights reserved. . . . . . . 304

vii

viii IBM Workload Automation: Scheduling Applications with IBM Workload Automation

Tables

1. Job plug-ins . . . . . . . . . . . . . 12. Access methods . . . . . . . . . . . 23. Required and optional attributes for the

definition of an IBM BigInsights job . . . . 154. Required and optional attributes for the

definition of an IBM Cloudant job . . . . . 195. Required and optional attributes for the

definition of jobs running IBM Cognos reports. 266. Examples to use for parameters of date, time,

and time stamp formats . . . . . . . . 317. Properties for running IBM Cognos reports 348. Mapping between IBM Workload Scheduler

job statuses and IBM Cognos report statuses . 379. Required and optional attributes for the job

definition of IBM InfoSphere DataStage jobs. . 4210. Properties to run IBM InfoSphere DataStage

jobs . . . . . . . . . . . . . . . 4811. Mapping between IBM Workload Scheduler

and IBM InfoSphere DataStage job statuses . . 4812. Required and optional attributes for the

definition of an IBM Sterling Connect:Directjob . . . . . . . . . . . . . . . 53

13. Required and optional attributes for thedefinition of an IBM WebSphere MQ job . . . 63

14. Required and optional attributes for thedefinition of a Hadoop Distributed File Systemjob . . . . . . . . . . . . . . . 69

15. Required and optional attributes for thedefinition of a Hadoop Map Reduce job . . . 73

16. Required and optional attributes for thedefinition of an Oozie job . . . . . . . . 77

17. Required and optional attributes for the jobdefinition of PowerCenter jobs. . . . . . . 82

18. Mapping between IBM Workload Schedulerjob statuses and PowerCenter workflowstatuses . . . . . . . . . . . . . . 92

19. Required and optional attributes for the jobdefinition of Oracle E-Business Suite jobs. . . 96

20. Properties to run Oracle E-Business Suite jobs 10021. Mapping between IBM Workload Scheduler

and Oracle E-Business Suite applicationstatuses . . . . . . . . . . . . . 101

22. Required and optional attributes for thedefinition of a Salesforce job . . . . . . 105

23. How to complete the extended agentsdefinition . . . . . . . . . . . . . 121

24. Roles and responsibilities in Access methodfor PeopleSoft . . . . . . . . . . . 129

25. Psagent access method options. . . . . . 13126. Task string parameters for PeopleSoft jobs 13727. Relationship between the run status, the

distribution status, and the IBM WorkloadScheduler job status . . . . . . . . . 139

28. Relationship between the run status and theIBM Workload Scheduler job status . . . . 139

29. Roles and responsibilities in Access methodfor z/OS . . . . . . . . . . . . . 141

30. SYSTSIN variables . . . . . . . . . . 14731. File characteristics for obtaining the gateway

fix pack files by FTP . . . . . . . . . 14932. File characteristics for the LOADLIB file after

receiving it . . . . . . . . . . . . 15133. File characteristics for the SAMPLIB file after

receiving it . . . . . . . . . . . . 15134. Access method for z/OS access method

options . . . . . . . . . . . . . 15235. JES job states with respect to IBM Workload

Scheduler . . . . . . . . . . . . . 15836. IBM Workload Scheduler for z/OS operation

states with respect to IBM WorkloadScheduler . . . . . . . . . . . . . 159

37. IBM Workload Scheduler for z/OS operationoccurrence states with respect to IBMWorkload Scheduler . . . . . . . . . 160

38. Job states and return codes for the PeopleSoftaccess method . . . . . . . . . . . 167

39. IBM Workload Scheduler for SAP features 17640. Roles and responsibilities in IBM Workload

Scheduler for SAP . . . . . . . . . . 18041. Access keywords for activities with SAP

scheduling objects . . . . . . . . . . 18242. ABAP/4 modules installed according to the

SAP release . . . . . . . . . . . . 18743. ABAP/4 modules contents . . . . . . . 18944. r3batch global configuration options . . . . 19545. r3batch local configuration options . . . . 19646. r3batch common configuration options 19847. Placeholders and counters for extended

variants . . . . . . . . . . . . . 21748. Task string parameters for SAP jobs . . . . 22149. Status transitions in IBM Workload Scheduler

(internal status) and the corresponding SAPR/3 status . . . . . . . . . . . . 229

50. Task string parameters for SAP jobs (dynamicdefinition) . . . . . . . . . . . . 237

51. Supported attributes for ABAP step definition 24352. Supported attributes for external programs

and external commands step definition . . . 24553. Placeholders for job interception template

files . . . . . . . . . . . . . . . 26054. Task string parameters for SAP R/3 jobs 26555. Actions performed when you rerun a process

chain job . . . . . . . . . . . . . 27156. Parameters to define an SAP internetwork

dependency . . . . . . . . . . . . 28557. Internetwork dependency definition and

possible resolution . . . . . . . . . . 28758. History table of the SAP events raised 29059. SAP event matching with the event rule

defined . . . . . . . . . . . . . 29060. History table of the SAP events raised 291

ix

||||||

||||||||||||||

|||

61. SAP events matching with the event ruledefined . . . . . . . . . . . . . 291

62. IBM Workload Scheduler fields used to defineevent rules based on IDocs . . . . . . . 294

63. IBM Workload Scheduler fields used to definecorrelation rules for IDoc events . . . . . 294

64. Parameters of IDOCEventGenerated eventtype. . . . . . . . . . . . . . . 295

65. Standard outbound IDoc statuses . . . . . 29666. Standard inbound IDoc statuses . . . . . 29767. Mapping between root context MTE name

and IBM Workload Scheduler fields . . . . 30468. Mapping between summary context MTE

name and IBM Workload Scheduler fields . . 30569. Mapping between object MTE name and IBM

Workload Scheduler fields . . . . . . . 305

70. Mapping between attribute MTE name andIBM Workload Scheduler fields . . . . . 306

71. Alert properties for correlations . . . . . 30672. SAP R/3 supported code pages . . . . . 31273. Miscellaneous troubleshooting items . . . . 31374. Required and optional attributes for the job

definition of SAP PI Channel jobs. . . . . 32575. Mapping between IBM Workload Scheduler

and SAP PI Channel job statuses . . . . . 32776. Required and optional attributes for the

definition of a SAP BusinessObjects BI job . . 33077. Properties for the smseadapter.properties

file. . . . . . . . . . . . . . . . 338

x IBM Workload Automation: Scheduling Applications with IBM Workload Automation

|||

About this Publication

This guide provides information about how to set up and use IBM WorkloadScheduler. It contains the following information:v Job plug-ins or adaptors for the following applications:

IBM BigInsights IBM Cognos IBM Cloudant IBM InfoSphere DataStage IBM Sterling Connect:Direct IBM WebSphere MQ Hadoop Distributed File System Hadoop Map Reduce Apache Oozie Informatica PowerCenter Oracle E-Business Suite Salesforce SAP BusinessObjects BI SAP PI Channel

v Access methods that run and control jobs of the following applications: PeopleSoft SAP R/3 z/OS

v Integration with SAP: SAP R/3 access method Job plug-in for SAP BusinessObjects BI Job plug-in for SAP PI Channel Integration with SAP Solution Manager

What is new in this releaseLearn what is new in this release.

For information about the new or changed functions in this release, see IBMWorkload Automation: Overview, section Summary of enhancements.

For information about the APARs that this release addresses, see the IBM WorkloadScheduler Release Notes at http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg27048863 and the Dynamic Workload Console Release Notes athttp://www-01.ibm.com/support/docview.wss?rs=672&uid=swg27048864.

New or changed content is marked with revision bars. For the PDF format, new orchanged V9.4 content is marked in the left margin with a pipe (|) character andnew or changed V9.4FP1 content is marked with an equal sign (=).

Who should read this publicationLearn who should read this publication.

xi

|

===

http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg27048863http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg27048863http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg27048864

This publication is intended for job schedulers who want to run and controlapplication jobs by using IBM Workload Scheduler. Readers of this publicationshould have some knowledge of:v IBM Workload Schedulerv Dynamic Workload Consolev The specific application environment.

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully.

With this product, you can use assistive technologies to hear and navigate theinterface. You can also use the keyboard instead of the mouse to operate allfeatures of the graphical user interface.

For full information, see the Accessibility Appendix in the IBM Workload SchedulerUser's Guide and Reference.

Technical trainingCloud & Smarter Infrastructure provides technical training.

For Cloud & Smarter Infrastructure technical training information, see:http://www.ibm.com/software/tivoli/education

Support informationIBM provides several ways for you to obtain support when you encounter aproblem.

If you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:v Searching knowledge bases: You can search across a large collection of known

problems and workarounds, Technotes, and other information.v Obtaining fixes: You can locate the latest fixes that are already available for your

product.v Contacting IBM Software Support: If you still cannot solve your problem, and

you need to work with someone from IBM, you can use a variety of ways tocontact IBM Software Support.

For more information about these three ways of resolving problems, see theappendix about support information in IBM Workload Scheduler: TroubleshootingGuide.

How to read syntax diagramsSyntax diagrams help to show syntax in a graphical way.

Throughout this publication, syntax is described in diagrams like the one shownhere, which describes the SRSTAT TSO command:

xii IBM Workload Automation: Scheduling Applications with IBM Workload Automation

http://www.ibm.com/software/tivoli/education

SRSTAT ' resource name 'OPCA

SUBSYS ( subsystem name )MSTR

KEEP

AVAIL ( RESET )NOYES

KEEPDEVIATION ( amount )

RESET

KEEP

QUANTITY ( amount )RESET

YESCREATE ( NO )

0

TRACE ( trace level )

The symbols have these meanings:

The statement begins here.

The statement is continued on the next line.

The statement is continued from a previous line.

The statement ends here.

Read the syntax diagrams from left to right and from top to bottom, following thepath of the line.

These are the conventions used in the diagrams:v Required items appear on the horizontal line (main path):

STATEMENT required item

v Optional items appear below the main path:

STATEMENToptional item

v An arrow returning to the left above the item indicates an item that you canrepeat. If a separator is required between items, it is shown on the repeat arrow.

STATEMENT

,

repeatable item

v If you can choose from two or more items, they appear vertically in a stack. If you must choose one of the items, one item of the stack appears on the

main path:

About this Publication xiii

STATEMENT required choice 1required choice 2

If choosing one of the items is optional, the entire stack appears below themain path:

STATEMENToptional choice 1optional choice 2

A repeat arrow above a stack indicates that you can make more than onechoice from the stacked items:

STATEMENT

,

optional choice 1optional choice 2optional choice 3

STATEMENT

,

required choice 1required choice 2required choice 3

v Parameters that are above the main line are default parameters:

STATEMENTdefault

alternative

v Keywords appear in uppercase (for example, STATEMENT).v Parentheses and commas must be entered as part of the command syntax, as

shown.v For complex commands, the item attributes might not fit on one horizontal line.

If that line cannot be split, the attributes appear at the bottom of the syntaxdiagram:

STATEMENT required choice 1option 1 option 2

required choice 2required choice 3

option 1

defaultoptional choice 1 ( alternative )

xiv IBM Workload Automation: Scheduling Applications with IBM Workload Automation

option 2

defaultoptional choice 2 ( alternative )

About this Publication xv

xvi IBM Workload Automation: Scheduling Applications with IBM Workload Automation

Part 1. Overview

Learn about plug-ins and access methods and how you can use them to extendIBM Workload Scheduler scheduling capabilities to external applications andsystems.

Important: The plug-ins and access methods listed are included with IBMWorkload Scheduler, but to be entitled to use them, you must purchase a separatechargeable component in addition to IBM Workload Scheduler or purchase the IBMWorkload Scheduler for z/OS Agent, which includes the plug-ins and accessmethods. See the IBM Workload Scheduler Download document for details:http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg24042843. Forinformation about the supported versions of the plug-ins and access methods, runthe Data Integration report and select the Supported Software tab.

You can extend job scheduling capabilities with IBM Workload Scheduler plug-insto external applications to take advantage of all the IBM Workload Schedulerfunctions to manage the operations and tasks performed by the externalapplications.

The plug-ins are:

Table 1. Job plug-ins

Job Plug-in More information

IBM BigInsights Chapter 6, IBM BigInsights jobs, on page15

IBM Cloudant Chapter 7, IBM Cloudant jobs, on page 19

IBM Cognos Chapter 8, IBM Cognos jobs, on page 23

IBM InfoSphere DataStage Chapter 9, IBM InfoSphere DataStage jobs,on page 41

IBM Sterling Connect:Direct Chapter 10, IBM Sterling Connect:Directjobs, on page 53

IBM WebSphere MQ Chapter 11, IBM WebSphere MQ jobs, onpage 63

Hadoop Distributed File System Chapter 12, Hadoop Distributed FileSystem jobs, on page 69

Hadoop Map Reduce Chapter 13, Hadoop Map Reduce jobs, onpage 73

Apache Oozie Chapter 14, Apache Oozie jobs, on page 77

Informatica PowerCenter Chapter 15, Informatica PowerCenter jobs,on page 81

Oracle E-Business Suite Chapter 16, Oracle E-Business Suite jobs,on page 95

Salesforce Chapter 17, Salesforce jobs, on page 103

SAP BusinessObjects BI SAP BusinessObjects BI jobs on page 328

SAP PI Channel SAP Process Integration (PI) Channel jobson page 323

1

http://www-01.ibm.com/support/docview.wss?rs=672&uid=swg24042843http://www-969.ibm.com/software/reports/compatibility/clarity-reports/report/html/softwareReqsForProduct?deliverableId=1393949467532&osPlatforms=AIX|HP|IBM%20i|Linux|Solaris|Windows|z/OS&duComponentIds=S002|S001|A005|A003|A004&mandahttp://www-969.ibm.com/software/reports/compatibility/clarity-reports/report/html/softwareReqsForProduct?deliverableId=1393949467532&osPlatforms=AIX|HP|IBM%20i|Linux|Solaris|Windows|z/OS&duComponentIds=S002|S001|A005|A003|A004&mandatoryCapIds=30|9|13|121|25|26&optionalCapIds=130|132toryCapIds=30|9|13|121|25|26&optionalCapIds=130|132

You can use access methods to extend the job scheduling capabilities of IBMWorkload Scheduler to other systems and applications. Access methods run on:v Extended agents to extend static scheduling capability.v Dynamic agents and IBM Workload Scheduler for z/OS Agents to extend

dynamic scheduling capability.

For more details about which workstations can run the access methods, seeChapter 1, Supported agent workstations, on page 3.

An access method interacts with the external system through either its commandline or the Dynamic Workload Console. IBM Workload Scheduler includes thefollowing access methods:

Table 2. Access methods

Access Method More information

SAP R/3 (r3batch) Configuring the SAP R/3 environment onpage 182

PeopleSoft (psagent) Chapter 19, Access method for PeopleSoft,on page 129

z/OS (mvsjes and mvsopc) Chapter 20, Access method for z/OS, onpage 141

2 IBM Workload Automation: Scheduling Applications with IBM Workload Automation

Chapter 1. Supported agent workstations

You can extend IBM Workload Scheduler scheduling capabilities to externalapplications by using plug-ins and access methods.

To extend scheduling capabilities to external applications by using IBM WorkloadScheduler job plug-ins, you must install either a dynamic agent or an IBMWorkload Scheduler for z/OS Agent (z-centric), or both.

To extend scheduling capabilities to external applications, such as PeopleSoft, SAPR/3, and z/OS JES2 or JES3 by using IBM Workload Scheduler access methods,you must have at least one, or a combination of, the following types of agentworkstations: dynamic agent, extended agent, and IBM Workload Scheduler forz/OS Agent (z-centric).

These agent workstations are described as follows:

Dynamic agents and IBM Workload Scheduler for z/OS agents

Dynamic agents and IBM Workload Scheduler for z/OS agents can managea wide variety of job types. They are used to extend the dynamicscheduling capabilities of IBM Workload Scheduler to your externalapplications through appropriate job plug-ins.

Dynamic agents and IBM Workload Scheduler for z/OS agents also extendthe dynamic scheduling capabilities to external applications through accessmethods. To run access methods on external applications using dynamicagents, you define a job of type Access Method. The access methodcommunicates with the external system to launch the job and returns thestatus of the job. The method uses the corresponding file namedoptionsfile_accessmethod.opts (where optionsfile is the configurationfile that depends on the selected access method). The dynamic agent andthe IBM Workload Scheduler for z/OS agent can have more than oneassociated .opts file to determine which external environment instance itconnects to. The access method can launch jobs on that instance andmonitor them through completion, writing job progress and statusinformation in the standard list file of the job.

Dynamic agents in particular, can be grouped in pools and dynamic pools.Pools group a set of dynamic agents with similar hardware or softwarecharacteristics together. When jobs are submitted to a pool, IBM WorkloadScheduler balances the jobs among the dynamic agents within the pool.Dynamic pools are dynamically defined based on the resourcerequirements specified. A pool is dynamically updated whenever a newsuitable dynamic agent becomes available. Jobs run on the first workstationin the dynamic pool that matches all the requirements of the job.

Extended agents

Extended agents extend the static scheduling capability. They are logicalworkstations related to an access method hosted by a physical IBMWorkload Scheduler workstation (a fault-tolerant agent). More than oneextended agent workstation can be hosted by the same IBM WorkloadScheduler fault-tolerant agent and rely on the same access method. Theextended agent is defined in a standard IBM Workload Schedulerworkstation definition, which gives the extended agent a name and

3

identifies the access method. An access method is a program that is run bythe hosting workstation whenever IBM Workload Scheduler submits a jobto an external system.

Jobs are defined for an extended agent in the same manner as for otherIBM Workload Scheduler workstations, except for any job attributes thatdepend on the external system or application.

To launch and monitor a job on an extended agent, the host runs the accessmethod, passing to it job details as command line options. The accessmethod communicates with the external system to launch the job andreturns the status of the job. To launch a job in an external environment,IBM Workload Scheduler runs the extended agent access method providingit with the extended agent workstation name and information about thejob. The method looks at the corresponding file namedXANAME_accessmethod.opts (where XANAME is the name of the extendedagent workstation) to determine which external environment instance itconnects to. The access method can then launch jobs on that instance andmonitor them through completion, writing job progress and statusinformation in the standard list file of the job.

Extended agents can also be used to run jobs in an end-to-endenvironment, where job scheduling and monitoring is managed from anIBM Workload Scheduler for z/OS controller.


Part 2. Job plug-ins to extend workload schedulingcapabilities

A wide variety of out-of-the-box adaptors or plug-ins are provided to integrateyour business processes. The job plug-ins allow you to orchestrate EnterpriseResource Planning and Business Intelligence solutions (PeopleSoft, OracleE-Business, Informatica PowerCenter, Salesforce) and other business relatedsystems. New applications are added to your organization all the time. Byintegrating them into your existing IBM Workload Scheduler environment yousave time in getting skilled on new applications because you can administer themjust like any of your existing jobs.

By extending the concept of jobs and workload scheduling to other applicationsyou can continue to define jobs for your business process, add them to job streams,submit them to run according to schedule, and then monitor any exceptions allfrom a single entry point. The job plug-ins require an IBM Workload Schedulerdynamic agent, IBM Workload Scheduler for z/OS Agent (z-centric), or both. Formore information, see Chapter 1, Supported agent workstations, on page 3.

The following sections provide an overview of creating job definitions and jobstreams, submitting them to run, monitoring them, and then analyzing the job logand job output. These procedures can be applied to any of the supported jobplug-ins.

For information about the supported versions of the job plug-ins, generate adynamic Data Integration report from the IBM Software Product CompatibilityReports web site, and select the Supported Software tab: Data Integration.

Tip: Many of the IBM Workload Scheduler job plug-ins are illustrated in helpful,how-to demonstrations videos available on the Workload Automation YouTubechannel.

5

http://www-969.ibm.com/software/reports/compatibility/clarity-reports/report/html/softwareReqsForProduct?deliverableId=196702D00EBC11E58BF1AF9D8B1D437A&osPlatforms=AIX|HP|IBM%20i|Linux|Solaris|Windows|z/OS&duComponentIds=S002|S001|A005|A003|A004&mandatoryCapIds=30|9|13|121|25|26&optionalCapIds=130|132https://www.youtube.com/user/workloadautomation2https://www.youtube.com/user/workloadautomation2

Chapter 2. Defining a job

Define IBM Workload Scheduler jobs to run business tasks and processes definedin an external application.

Define an IBM Workload Scheduler job to run tasks or processes you have definedin external applications. Using the IBM Workload Scheduler job plug-in for yourexternal application, you can define, schedule and run jobs to automate yourbusiness.

Distributed

In distributed environment, define a job by using the Dynamic

Workload Console connected to a distributed engine, by using Application Lab, orby using the composer command line.

z/OS

In a z/OS environment, define a job by using the Dynamic Workload

Console connected to a z/OS engine.

How to define a job using the Dynamic Workload ConsoleFor details about defining jobs from the Dynamic Workload Console, seethe section about creating job definitions in Dynamic Workload ConsoleUser's Guide.

How to define a step (job) inside a process (job stream) using Application LabFor details about defining a step (job) inside a process (job stream) usingApplication Lab see the section about creating a process in Application LabUser's Guide.

How to define a job using the composer command lineThe composer command line supports the following syntax when defininga job:

$jobs[workstation#]jobname

{scriptname filename streamlogon username |docommand "command" streamlogon username |task job_definition }

[description "description"][tasktype tasktype][interactive]

[succoutputcond Condition_Name "Condition_Value"][outputcond Condition_Name "Condition_Value"]

[recovery{stop[after [workstation#]jobname][abendprompt "text"]]

|continue[after [workstation#]jobname][abendprompt "text"]] |rerun [same_workstation]

[[repeatevery hhmm] [for number attempts]][after [workstation#]jobname]|[after [workstation#]jobname]

[abendprompt "text"]}

7

==

Use the task argument, specifying the XML syntax for the specific jobplug-in. See the section for each job plug-in for the specific XML syntax.

For a detailed description of the XML syntax, see the section about jobdefinition in User's Guide and Reference.

For some jobs a properties file can be generated and used to provide the values forsome of the properties defined in the job definition.

The properties file is automatically generated either when you perform a "TestConnection" from the Dynamic Workload Console in the job definition panels, orwhen you submit the job to run the first time. Once the file has been created, youcan customize it. This is especially useful when you need to schedule several jobsof the same type. You can specify the values in the properties file and avoidhaving to provide information such as credentials and other information, for eachjob. You can override the values in the properties files by defining different valuesat job definition time.


Chapter 3. Scheduling and submitting jobs and job streams

You schedule IBM Workload Scheduler jobs by defining them in job streams.

Distributed

For distributed environments, use the Dynamic Workload Console,

Application Lab or the conman command line.

After you define an IBM Workload Scheduler job, add it to a job stream with allthe necessary scheduling arguments and submit it to run. After submission, whenthe job is running (EXEC status), you can kill the IBM Workload Scheduler job ifnecessary. For some job plug-ins, this action is converted into corresponding actionin the plug-in application. Refer to the specific plug-in section for details aboutwhat effect the kill action has in the application.

z/OS

For z/OS environments, use the Dynamic Workload Console or the ISPF

application.

How to submit a job stream using the Dynamic Workload ConsoleTo submit a job or job stream to run according to the schedule defined, seethe section about submitting workload on request in production inDynamic Workload Console User's Guide. For distributed environments only,see also the section about quick submit of jobs and job streams in DynamicWorkload Console User's Guide.

How to submit a process (job stream) using Application LabTo submit a process to run according to the schedule defined for it, see thesection about running a process in Application Lab User's Guide.

How to submit a job stream from the conman command lineTo submit a job stream for processing, see the submit sched command. Tosubmit a job to be launched, see the submit job command. For moreinformation about these commands see the IBM Workload Scheduler: User'sGuide and Reference.

How to submit your workload using the ISPF applicationThe workload is defined by creating one or more calendars, definingapplications, creating a long-term plan, and creating a current plan. Thecurrent plan is a detailed plan, typically for one day, that lists theapplications that run and the operations in each application. See the sectionabout creating the plans for the first time in Managing the Workload formore information about creating plans.

9

Chapter 4. Monitoring IBM Workload Scheduler jobs

Monitor IBM Workload Scheduler jobs by using the Dynamic Workload Console,the command line, Application Lab, or the ISPF application.

Distributed

You monitor distributed jobs by using the Dynamic Workload Console

connected to a distributed engine, by using the conman command line, or fromApplication Lab.

z/OS

You monitor z/OS jobs by using the Dynamic Workload Console

connected to a z/OS engine or the ISPF application.

How to monitor jobs by using the Dynamic Workload ConsoleSee the online help or the section about creating a task to monitor jobs inthe Dynamic Workload Console User's Guide.

How to monitor jobs by using conman See the section about managing objects in the plan - conman in User'sGuide and Reference.

How to monitor jobs by using Application LabSee the section about monitoring your process in Application Lab User'sGuide.

How to monitor jobs by using the ISPF applicationSee the section about monitoring the workload in IBM Workload Schedulerfor z/OS Managing the Workload.

11

Chapter 5. Analyzing the job log

When a job runs IBM Workload Scheduler creates a job log that you can analyze toverify the job status.

Distributed

For distributed jobs, you analyze the job log by using the Dynamic

Workload Console, Application Lab or the conman command line.

z/OS

For z/OS jobs, you analyze the job log by using the Dynamic Workload

Console or the ISPF application.

While the job is running, you can track the status of the job and analyze theproperties of the job. In particular, in the Extra Information section, if the jobcontains variables, you can verify the value passed to the variable from the remotesystem. Some job streams use the variable passing feature, for example, the valueof a variable specified in job 1, contained in job stream A, is required by job 2 inorder to run in the same job stream.

For more information about passing variables between jobs, see the related sectionin the IBM Workload Scheduler on-premises online product documentation in IBMKnowledge Center.

How to analyze the job log using the Dynamic Workload ConsoleBefore you can access the job log for an individual job, you need to run aquery and list the jobs for which you want to analyze the job log. See theonline help or the section about creating a task to monitor jobs in DynamicWorkload Console User's Guide. From the list of jobs resulting from thequery, you can either download the job log, or view the job log in the jobproperties view. Select the job for which you want to analyze the job logand click More Actions > Download Job Log or More Actions >Properties from the toolbar.

How to analyze the job log using Application LabIn Application Lab, a process is the equivalent of a job stream. From thelist of processes displayed for the selected process library, select a processand then click the History tab. A run history for the process is displayed.Select a run instance and click Details. A list of steps defined in theprocess is displayed. Each step is the equivalent of a job. To view the logfor a step or download the log, select a step and click View Log orDownload Log, as needed.

For more information about Application Lab, see Application Lab User'sGuide.

How to analyze the job log using conman See the section about the showjobs command in User's Guide and Reference.

How to analyze the job log using the ISPF applicationSee the section about monitoring the workload in Managing the Workload.

13

Chapter 6. IBM BigInsights jobs

An IBM BigInsights job defines, schedules, monitors, and manages IBM BigInsightsWorkbook data sheets or applications.

Prerequisite

You manage IBM BigInsights Workbook data sheets or applications in both adistributed and z/OS environment.

IBM Workload Scheduler integrates with IBM BigInsights for Hadoop to bring thepower of Apache Hadoop to the enterprise. With the IBM Workload Schedulerplug-in for BigInsights for Hadoop you can:v Monitor and control workflows containing IBM BigInsights workbooks and

applications that help enterprise find insights into new and emerging types ofdata.

v Fully automate IBM BigInsights process execution with calendar andevent-based scheduling, and a single point of control to handle exceptions, andautomate recovery processes.

Before you can define IBM BigInsights jobs, you must create a connection betweenthe IBM Workload Scheduler agent and the IBM BigInsights server.


IBM BigInsights job definition

A description of the job properties and valid values are detailed in thecontext-sensitive help in the Dynamic Workload Console by clicking the questionmark (?) icon in the top-right corner of the properties pane.

For more information about creating jobs using the various supported productinterfaces, see Chapter 2, Defining a job, on page 7.

The following table lists the required and optional attributes for IBM BigInsightsjobs:

Table 3. Required and optional attributes for the definition of an IBM BigInsights job

Attribute Description and value Required

Connection properties - IBM BigInsights server section

Hostname The hostname of the IBM BigInsights server. U

Port The port of the IBM BigInsights server. U

Protocol The protocol for connecting to the IBM BigInsightsserver. Supported values are http and https.

User The user to be used for accessing the IBM BigInsightsserver.

Password The password to be used for accessing the IBMBigInsights server.

15

|

|

||

|

||

|||

|||

|||

||

|||

|

|||

||

||

||

|||

|

|||

|||

||||

||||

||||

http://www-969.ibm.com/software/reports/compatibility/clarity-reports/report/html/softwareReqsForProduct?deliverableId=196702D00EBC11E58BF1AF9D8B1D437A&osPlatforms=AIX|HP|IBM%20i|Linux|Solaris|Windows|z/OS&duComponentIds=S002|S001|A005|A003|A004&mandatoryCapIds=30|9|13|121|25|26&optionalCapIds=130|132

Table 3. Required and optional attributes for the definition of an IBM BigInsightsjob (continued)


Connection properties - Retry options section

Number of retries The number of times the program retries performingthe operation.

Retry interval(seconds)

The number of seconds the program waits beforeretrying the operation. The default value is 30seconds.

Action properties - Workbook section

Workbook The name and path to an IBM BigInsights workbook.Use this option to run a user-specified workbook.

U

Action properties - Application section

Application Identifier The application identifier. Use this option to run anApplication.

U

Execution Name The user-defined identifier for a specific run of theapplication

Scheduling and stopping the job in IBM Workload Scheduler

You schedule IBM Workload Scheduler IBM BigInsights jobs by defining them injob streams. Add the job to a job stream with all the necessary schedulingarguments and submit the job stream.

You can submit jobs by using the Dynamic Workload Console, Application Lab orthe conman command line. See Chapter 3, Scheduling and submitting jobs and jobstreams, on page 9 for information about how to schedule and submit jobs andjob streams using the various interfaces.

After submission, when the job is running and is reported in EXEC status in IBMWorkload Scheduler, you can stop it if necessary, by using the kill command.However, this action is effective only for the Wait for a file action. If you havedefined different actions in your job, the kill command is ignored.

Monitoring the job

If the IBM Workload Scheduler agent stops when you submit the IBM WorkloadScheduler IBM BigInsights job or while the job is running, as soon as the agentbecomes available again IBM Workload Scheduler begins monitoring the job fromwhere it stopped.

For information about how to monitor jobs using the different product interfacesavailable, see Chapter 4, Monitoring IBM Workload Scheduler jobs, on page 11.

Job properties



||

|||

|

||||

|||||

|

|

||||

|

||||

||||

|

|

|||

||||

||||

|

||||

||

|

||||||

For information about how to display the job properties from the varioussupported interfaces, see Chapter 5, Analyzing the job log, on page 13.

For example, from the conman command line, you can see the job properties byrunning:conman sj ;props

where is the IBM BigInsights job name.

The properties are listed in the Extra Information section of the output command.

For more information about passing variables between jobs, see the related sectionsin User's Guide and Reference.

Job log content

For information about how to display the job log from the various supportedinterfaces, see Chapter 5, Analyzing the job log, on page 13.

For example, you can see the job log content by running conman sj;stdlist, where is the IBM BigInsights job name.

See also

From the Dynamic Workload Console you can perform the same task as describedin

the Dynamic Workload Console User's Guide, section about Creating job definitions.

For more information about how to create and edit scheduling objects, see

the Dynamic Workload Console User's Guide, section about Designing your Workload.

Chapter 6. IBM BigInsights jobs 17

||

||

|

|

|

||

|

||

||

|

||

|

|

|

Chapter 7. IBM Cloudant jobs

An IBM Cloudant job defines, schedules, monitors, and controls the execution ofactions on IBM Cloudant NoSQL database, on its documents, or attachments.

Prerequisites


Before you can define IBM Cloudant jobs, you must sign up on IBM Cloudant andcreate an account.

IBM Cloudant job definition

A description of the job properties and valid values are detailed in thecontext-sensitive help in the Dynamic Workload Console by clicking the questionmark (?) icon in the top-right corner of the properties pane.


The following table lists the required and optional attributes for IBM Cloudantjobs:

Table 4. Required and optional attributes for the definition of an IBM Cloudant jobAttribute Description and value Required

Connection

Username The name of the user authorized to access the Cloudant database. If you do notspecify thisattribute, thenthe attribute isread from theproperties file.

Password The password that is associated with the user authorized to access theCloudant database.

If you do notspecify thisattribute, thenthe attribute isread from theproperties file.

AccountText The account that was created when you signed up on Cloudantdatabase.

If you do notspecify thisattribute, thenthe attribute isread from theproperties file.

DatabaseText The Cloudant database that you want to work with. If you do notspecify thisattribute, thenthe attribute isread from theproperties file.

Action

Database Action

19

|

|

||

|

|||

||

|

|||

||

||

||||||||||||||||||||||||||||||||||||||||||


Table 4. Required and optional attributes for the definition of an IBM Cloudantjob (continued)


DatabaseOperation The action that you want to run on the Cloudant database:

v Create

v Read

v Delete

U

Database ReplicationAction

TargetDb The target Cloudant database that you want to synchronize with yoursource Cloudant database. If the target database does not exist, it iscreated automatically, unless you specify create_target=false in thelist of Operation Parameters.

U

Document Action

DocumentOperation The action that you want to run on the Cloudant database document:

v Create

v Read

v Update

v Delete

U

IdDocument The document identifier. U

RevDocument The document revision number. For the delete action, it must be equalto the latest revision number.

This attributeis required forthe update anddelete actions.

Attachment Action

AttachmentOperation The action that you want to run on the document attachment:

v Create

v Read

v Update

v Delete

U

IdDocument2 The identifier of the document to which the attachment refers to. U

RevDocument2 The revision number of the document to which the attachment refersto. For the delete action, it must be equal to the latest revisionnumber.

This attributeis required forthe update anddelete actions.

NameAttach The name by which the attachment is associated with the document.For the update action, if the attachment does not exist, it is createdautomatically. For the create action, if the attachment already exists, itis updated automatically.

U

ContentTypeAttach The attachment content type header. U

DestinationAttach For the read action, the name of the file where you want to receivethe attachment.

Operation Parameters

OperationParameters The list of additional parameters that you can add for the readdocument and the database replication actions.

No check is performed at job definition time on the extra parameters .For details about operation parameters, see the IBM Cloudantdocumentation.

Body

InputFileName The path and name of the file containing the document or attachmentcontent.

InputDocument The document content. This attribute does not apply to attachments.To create or update a document with an empty content, specify {}.

Scheduling and stopping a job in IBM Workload Scheduler

You schedule IBM Workload Scheduler IBM Cloudant jobs by defining them in jobstreams. Add the job to a job stream with all the necessary scheduling argumentsand submit the job stream.


||||||||||

|

||||

|||||

|

|||||||||

|

|||||||||||||||||

|

|||||||

|||||||||

|

|||||||

||||

|||

|

|||||

||||

|

|

|||

You can submit jobs by using the Dynamic Workload Console, Application Lab orthe conman command line. See Chapter 3, Scheduling and submitting jobs and jobstreams, on page 9 for information about how to schedule and submit jobs andjob streams using the various interfaces.

After submission, when the job is running and is reported in EXEC status in IBMWorkload Scheduler, you can stop it if necessary, by using the kill command. Thisaction stops also the program execution on the IBM Cloudant database.

Monitoring a job

If the IBM Workload Scheduler agent stops when you submit the IBM Cloudantjob, or while the job is running, the job restarts automatically as soon as the agentrestarts.

For information about how to monitor jobs using the different product interfacesavailable, see Chapter 4, Monitoring IBM Workload Scheduler jobs, on page 11.

CloudantJobExecutor.properties file


The TWS_INST_DIR\TWS\JavaExt\cfg\CloudantJobExecutor.properties file containsthe following properties:#Cloudant propertiesUsername=Password=AccountText=DatabaseText=

For a description of each property, see the corresponding job attribute descriptionin Table 4 on page 19.

Job properties


For information about how to display the job properties from the varioussupported interfaces, see Chapter 5, Analyzing the job log, on page 13. Forexample, from the conman command line, you can see the job properties byrunning:conman sj ;props

where is the IBM Cloudant job name.

Chapter 7. IBM Cloudant jobs 21

||||

|||

|

|||

||

|

||||||||

||

|||||

||

|

||||||

||||

|

|

The properties are listed in the Extra Information section of the output command.

For information about passing job properties, see the topic about passing jobproperties from one job to another in the same job stream instance in the User'sGuide and Reference.

The following example shows the job definition for an IBM Cloudant job thatdeletes a document:

cfalcxxxxxxxx0054fdc307-1b24-4323-9a91-adc817ac45xx-bluemix

mydb

DELETEclaudio

Job log content

For information about how to display the job log from the various supportedinterfaces, see Chapter 5, Analyzing the job log, on page 13.

For example, you can see the job log content by running conman sj;stdlist, where is the IBM Cloudant job name.

See also

From the Dynamic Workload Console you can perform the same task as describedin

the Dynamic Workload Console User's Guide, section about Creating job definitions.

For more information about how to create and edit scheduling objects, see

the Dynamic Workload Console User's Guide, section about Designing your Workload.


|

|||

||

|||||||||||||||||||||||||||||||||

|

||

||

|

||

|

|

|

Chapter 8. IBM Cognos jobs

Use the IBM Workload Scheduler plug-in for IBM Cognos to run IBM Cognosreports, interactive reports, query, and report views, using IBM WorkloadScheduler.

Take advantage of all the IBM Workload Scheduler scheduling capabilities tomanage these reports.

You manage these reports both in a distributed and in a z/OS environment, byselecting the appropriate engine.

Any reference in the documentation to reports is intended to mean reports,interactive reports, query, and report views, unless otherwise specified.


Business scenarioA retail company has many shops around the world. Each shop has its own localdatabase, which stores daily transactions and tracks the number of articlesremaining in stock. The central business division of the company every morningneeds to analyze all the reports that show the number of articles sold in everycountry, grouped by predefined categories.

The company collects this data by using IBM InfoSphere DataStage and creates thereports using IBM Cognos. Overnight, the company runs the following processes:v IBM InfoSphere DataStage jobs to collect data from the local database of each

store and then, using the procedures stored in the central database, to producethe aggregated data to create the business reports.

v IBM Cognos jobs to create the business reports to be used by the businessanalysts.

Both processes are performed manually by an operator. To reduce costs and toensure that the SLA requirement of having data available every morning issatisfied, the company wants to automate the entire process.

Using IBM Workload Scheduler Plug-in for IBM InfoSphere DataStage and for IBMCognos, the company can satisfy this objective because the product provides theplug-in necessary to automate and control the entire process.

Defining an IBM Workload Scheduler job to run an IBM Cognos reportDefine IBM Workload Scheduler jobs to run IBM Cognos reports by using one ofthe supported product interfaces.

Distributed

In a distributed environment, define an IBM Workload Scheduler job to

run an IBM Cognos report by using the Dynamic Workload Console connected to adistributed engine, by using Application Lab, or using the composer commandline.

23


z/OS In a z/OS environment, define an IBM Workload Scheduler job to runan IBM Cognos report by using the Dynamic Workload Console connected to az/OS engine.

See Chapter 2, Defining a job, on page 7 for more information about creatingjobs using the various interfaces available. Some samples of IBM Cognos report jobdefinitions are contained in the sections that follow.

Defining jobs by using the Dynamic Workload ConsoleYou can define IBM Workload Scheduler jobs to run IBM Cognos reports by usingthe Dynamic Workload Console.

To define a job by using the Dynamic Workload Console, perform the followingprocedure. See Chapter 2, Defining a job, on page 7 for information aboutdefining jobs with other available interfaces.1. In the console navigation tree, expand Administration > Workload Design and

click Manage Workload Definitions.2. Select an engine and click Go. The Workload Designer opens.3. In the Working List panel, select:

z/OS On z/OS egnine:New > Business Analytics > Cognos

Distributed

On a distributed engine:

New > Job Definition > Business Analytics > Cognos

The properties of the job are displayed in the right-hand panel for editing.4. In the properties panel, specify the attributes for the job definition you are

creating. You can find detailed information about all the attributes in the helpavailable with the panel. In particular:

In the General panel:Distributed

Environment:Enter the name of the IBM Workload Scheduler job that runsthe IBM Cognos report.

Enter the name of the workstation where you installed the IBMWorkload Scheduler agent.

z/OS

Environment:Enter the name of the partitioned data set where you want tocreate the JCL.

Enter the name of the JCL you want to create in the partitioneddata set.

Enter the name of the workstation where you installed the IBMWorkload Scheduler agent.

In the Cognos panel:

In the Credentials section:Enter the namespace and the credentials related to the IBMCognos report. If you do not want to specify them here, youcan define them in the CognosJobExecutor.properties file. In


this case IBM Workload Scheduler reads them from the.properties file when you retrieve any information by using alist or when you submit the job.

You do not need to specify this value if you set the true valuefor the Allow anonymous access? property in the IBM CognosConfiguration > Local Configuration > Security >Authentication > Cognos window.

In the Server connection section:Enter the host name or TCP/IP address and the port of theIBM Cognos server you want to connect to. If you do not wantto specify them here, you can define them in theCognosJobExecutor.properties file.

Select Use SSL connection security to communicate in SSL withthe IBM Cognos server. If you do not select it thecommunication is HTTP.

In the Report section:Enter the path to the report you want to run, the fully qualifiedpath where you want to save the report, the format in whichyou want to generate the report and parameters if required forthe report.

The path must exist and you must have the permission to writein it otherwise you receive an error message.

When you specify parameters that can have multiple values,use -Value: as separator. For example, you can write as follows:Rome-Value:Paris

Parameters of type date, time, and time stamp, must bespecified using a specific syntax. See Specifying the parameterformat for date, time, and time stamp on page 31.

Values for parameters that require parameterized filters must bespecified using the procedure described in Specifyingparameterized filters on page 31.

In the Delivery options panel:Use this panel to define the options to specify the delivery options forthe IBM Cognos report. If you did not insert a value in the Output filefield you must enter at least an email address.

5. Click Save to save the job definition in the database.

Job definition for IBM Cognos reportsJob definition properties and JSDL examples for IBM Cognos reports.


Table 5 on page 26 describes the required and optional attributes for the definitionof jobs to run IBM Cognos reports, together with a description of each attribute.

Chapter 8. IBM Cognos jobs 25

Table 5. Required and optional attributes for the definition of jobs running IBM Cognosreports.

Attribute Description/value Required

Namespace The IBM Cognos namespace tolog on to. It contains the IBMCognos objects, such asgroups, roles, data sources,distribution lists, and contacts.

You do not have to specify thisvalue if:

v You specified it in theCognosJobExecutor.properties file.

v You set the true value forthe Allow anonymousaccess? property in the IBMCognos Configuration >Local Configuration >Security > Authentication >Cognos window.

UserName The user to use when loggingon to the namespace.

U



v You set the true value for theAllow anonymous access?property in the IBM CognosConfiguration > LocalConfiguration > Security >Authentication > Cognoswindow.

password The password of theauthorized user. It is encryptedwhen you submit the job.





Table 5. Required and optional attributes for the definition of jobs running IBM Cognosreports. (continued)


serverAddress The host name or TCP/IPaddress of the IBM Cognosserver you want to connect to.




port The port to use for theconnection. The default valueis 9300. If you select Use SSL,the default is 9334. Fordetailed information, see theIBM Cognos documentation.




SslCheck Specify it to use SSLconnection security tocommunicate with the IBMCognos server. If you do notspecify it the communication isHTTP.

reportPath The path to the report that youwant to run.

U




parametersValues The list of parameters toassociate to the job.

When you specify parametersthat can have multiple values,use -Value: as separator. Forexample, you can write asfollows:

Rome-Value:Paris

Parameters of type date, time,and time stamp, must bespecified using a specificsyntax. See Specifying theparameter format for date,time, and time stamp on page31.

Values for parameters thatrequire parameterized filtersmust be specified using theprocedure described inSpecifying parameterizedfilters on page 31.

outputFile The fully qualified path whereyou want to save the report.The path must exist and youmust have the permission towrite in it. The report is savedwith the extensioncorresponding to the formatyou specified. IBM WorkloadScheduler saves, in the pathyou specify, the report with itscontent. You must specify atleast the path or an emailaddress for the deliveryoptions otherwise you receivean error message when yousave the job definition.




formatTypes The format in which you wantto generate the report.

For reports, supported formatsare:v CSVv Excel 2002v Excel 2007v HTMLv HTML Fragmentv HTML Web Archivev PDFv XML

For interactive reports andviews of interactive reportsyou can use only the HTMLformat. Even if, for a view ofan interactive report, you selecta format different from HTML,the product saves the output inHTML format when the jobruns.

The default value is HTML.

emailGroup The delivery options for theIBM Cognos report. If you didnot insert a value for theOutput file attribute, you mustenter at least an email address.The email delivery status doesnot impact the job completionstatus.

To, Cc, BccThe email addressesto which you want tosend the report.Address the messageby typing at least anemail address in oneof the address fields,To, Cc (carbon copy),or Bcc (blind carboncopy). To specifymultiple addressesdivide them by usingcommas.

SubjectThe subject of theemail.

Body The body of theemail.


The following example shows the job definition for an IBM Cognos report withonly the required attributes specified:$JOBSNC125152#COGNOS_ONLY_REQUIRED_FIELDSTASK

Address Report - Path:/content/package[@name=tws4apps]/report[@name=Address Report]

C:\outputFilePDF

RECOVERY STOP

The following example shows the job definition for an IBM Cognos report with allthe attributes specified:$JOBSNC125152#REPFOREUROPEBUSINESS COGNOS_ALL_FIELDSTASK

NTLMAdministrator{aes}SgB6gmS+3xj0Yq2QsINVOtsNCeZIIsMwt08kwO6ZCR4=

nc1120069300

date and time report - in values -

Path:/content/package[@name=cognosTime]/interactiveReport


[@name=date and time report - in values]

Between 2012-02-03 and 2012-04-15

-Value:01:00:00-Value:01:01:01

2012-02-03 15:05:00-Value:2012-02-03T16:01:00-Value:2012-02-03T16:00:00

C:\Cognos reports\ReportForEuropeBusiness

HTML

[email protected],[email protected]@[email protected] from CognosReport generated by Cognos:

RECOVERY STOP

Specifying the parameter format for date, time, and timestamp

When defining reports either using the Dynamic Workload Console, ApplicationLab or composer, specify parameters of type date, time, and time stamp, using aspecific syntax.

The following table shows the syntax you must use when defining reportscontaining date, time, and time stamp formats as parameters.

Table 6. Examples to use for parameters of date, time, and time stamp formats

Prompttype

Cognos parameterformat

Cognos parameter format examples

Singlevalue List of values Interval values

Date CCYY-MM-DD 2012-02-03 2012-02-03-Value:2012-03-14 Between 2012-02-03 and2012-04-15

Time hh:mm:ss 01:00:00 01:00:00-Value:01:01:01 Between 01:00:00 and 23:59:30

TimeStamp

CCYY-MM-DDThh:mm:ssorCCYY-MM-DD hh:mm:ss

2012-02-0315:05:00

2012-02-03 15:05:00-Value:2012-02-03T16:01:00-Value:2012-02-03T16:00:00

Between 2012-02-03 15:05:00and2012-04-15T16:00:00

Note: You must specify the parameter format exactly as they are shown in thetable respecting lower case and upper case formats.

Specifying parameterized filtersWhen defining reports that use parameterized filters either using the DynamicWorkload Console, Application Lab, or composer, for the value, use the onereported in the Cognos Report Studio.

The following example demonstrates how to specify parameters that useparameterized filters by using the Dynamic Workload Console:


1. In the Properties - Cognos page of the Workload Designer in the DynamicWorkload Console, click the Cognos tab.

2. Select the name of the parameter you want to specify for the report.3. In the Report section, click the addition (+) symbol for Parameter list to add a

new parameter.4. In the Name field, type the name of the parameter you want to specify for the

report.5. In the Value field, type the value reported in the Cognos Report Studio. To

identify the value proceed as follows:a. Open Report Studio.b. Open the report to run.c. In the Insertable Objects pane, select the filter you want to use. The

Properties page is displayed.d. Select the Ref value.

This example shows how to run the Cognos Employee Training by Year samplereport, specifying for the ?pYear? parameter the value associated with the filter2004. The Employee Training by Year sample report is located under/Samples/Models/Dashboard Objects. To run the report proceed as follows:1. In the Insertable Objects pane, select the 2004 filter. The Properties panel is

displayed.2. Select [go_data_warehouse].[2004].3. Insert [go_data_warehouse].[2004] in the Value field.4. Save the job definition.

To specify parameters that use parameterized filters using composer, perform thefollowing procedure.1. Open Report Studio.2. Open the report to run.3. In the Insertable Objects pane, select the filter you want to use. The Properties

panel is displayed.4. Select the Ref value.5. Copy this value in the attribute. Below an

example for the Employee Training by Year sample report specifying for the?pYear? parameter the value associated with the filter 2004:

Employee Training - Path:/content/folder[@name=Samples]/folder[@name=Models]/folder[@name=Dashboard Objects]/report[@name=Employee Training]

key="pYear">[go_data_warehouse].[2004]

C:\Cognos reports\Employee Training

HTML


Scheduling and submitting job streams for IBM Cognos reportsYou schedule IBM Workload Scheduler jobs for IBM Cognos reports by definingthem in job streams.

See Chapter 3, Scheduling and submitting jobs and job streams, on page 9 forinformation about how to schedule and submit jobs and job streams using thevarious interfaces.

After you define an IBM Workload Scheduler job for an IBM Cognos report, add itto a job stream with all the necessary scheduling arguments and submit it. Aftersubmission, when the job is running (EXEC status), you can kill the IBM WorkloadScheduler job that runs the IBM Cognos report if necessary. In particular, for IBMCognos jobs this action is converted into a Cancel action for the IBM Cognosreport.

The agent might become unavailable while the IBM Workload Scheduler jobrunning the IBM Cognos report is running. When the agent becomes availableagain, IBM Workload Scheduler starts to monitor the report from where it stopped.

For information about monitoring jobs and job streams, see Chapter 4, MonitoringIBM Workload Scheduler jobs, on page 11.

For information about analyzing the job log, see Chapter 5, Analyzing the joblog, on page 13.

Customizing IBM Workload Scheduler to run IBM Cognos reportsYou can customize IBM Workload Scheduler to run IBM Cognos report by usingthe CognosJobExecutor.properties file.

The CognosJobExecutor.properties file is a text file that contains the servercredentials, the authentication information, and the dispatch servlet name youspecified when configuring the IBM Cognos product.


The file is located in the directory:agent_install_dir/TWA/TWS/JavaExt/cfg

Where agent_install_dir is the path where you installed the IBM WorkloadScheduler dynamic agent or the IBM Workload Scheduler for z/OS agent. Whereagent_install_dir is the path where you installed the IBM Workload Schedulerdynamic agent.

You can define the properties contained in the .properties file, except thedispatchServlet value, at job definition time also. In this case, IBM Workload


Scheduler uses the values you specify at job definition time for running the report.Table 7 describes the properties contained in CognosJobExecutor.properties.

Table 7. Properties for running IBM Cognos reports

Property Description/value Required

namespace The IBM Cognos namespace to log on to.

You do not need to specify this value if you set thetrue value for the Allow anonymous access?property in the IBM Cognos Configuration >Local Configuration > Security > Authentication> Cognos window.

username The user to use when logging on to thenamespace.


password The password of the authorized user. It isencrypted in the agent configuration file when youretrieve any information by using a list, or whenyou submit the report.


serverAddress The host name or TCP/IP address of the Cognosserver you want to connect to.

serverPort The port to use for the connection. The defaultvalue is 9300. If you use SSL, the default is 9334.

dispatchServlet The dispatch you specified in the IBM CognosConfiguration > Environment > DispatcherSettings window. The default value is/p2pd/servlet/dispatch.

U

Example

This example shows a CognosJobExecutor.properties file.namespace=cognosNamespaceusername=userNamepassword=userPwdserverAddress=nc112006serverPort=9300dispatchServlet=/p2pd/servlet/dispatch

Configuring the agent to use Cognos in SSLConfigure the IBM Workload Scheduler agent to connect to an IBM Cognos serverthat is using SSL.

To configure the agent to connect to an IBM Cognos server that is using SSL,perform the following procedure.


Note: On Windows operating systems, path with blanks must be specifiedbetween double quotes.1. On the IBM Cognos server, run the following command to export the

certificate:

On Windows operating systems:\bin\ThirdPartyCertificateTool.bat -E -T-r \\-k \configuration\signkeypair\jCAKeystore-p

On UNIX and Linux operating systems:/bin/ThirdPartyCertificateTool -E -T-r //-k /configuration/signkeypair/jCAKeystore-p

where:

cognos_inst_pathSpecify the path where you installed the IBM Cognos server.

certificate_dirSpecify the directory in which to export the IBM Cognos certificate.

certificate_nameSpecify the name of the IBM Cognos certificate you export.

cognos_keystore_passwordSpecify the IBM Cognos password defined in the IBM CognosConfiguration > Security > Cryptography > Cognos - CertificateAuthority settings - Certificate Authority key store passwo

Documents

IBM Workload Automation: Scheduling Applications with IBM