HCL Workload Automation, Version 9.4

IBM Cloudant jobs

An IBM Cloudant job defines, schedules, monitors, and controls the execution of actions 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 and create an account.

IBM Cloudant job definition

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

For more information about creating jobs using the various supported product interfaces, see Defining a job.

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

Table 1. Required and optional attributes for the definition of an IBM Cloudant job
Attribute	Description and value	Required
Connection
Username	The name of the user authorized to access the Cloudant database.	If you do not specify this attribute, then the attribute is read from the properties file.
Password	The password that is associated with the user authorized to access the Cloudant database.	If you do not specify this attribute, then the attribute is read from the properties file.
AccountText	The account that was created when you signed up on Cloudant database.	If you do not specify this attribute, then the attribute is read from the properties file.
DatabaseText	The Cloudant database that you want to work with.	If you do not specify this attribute, then the attribute is read from the properties file.
Action
Database Action
DatabaseOperation	The action that you want to run on the Cloudant database: Create Read Delete	✓
Database Replication Action
TargetDb	The target Cloudant database that you want to synchronize with your source Cloudant database. If the target database does not exist, it is created automatically, unless you specify create_target=false in the list of Operation Parameters.	✓
Document Action
DocumentOperation	The action that you want to run on the Cloudant database document: Create Read Update Delete	✓
IdDocument	The document identifier.	✓
RevDocument	The document revision number. For the delete action, it must be equal to the latest revision number.	This attribute is required for the update and delete actions.
Attachment Action
AttachmentOperation	The action that you want to run on the document attachment: Create Read Update Delete	✓
IdDocument2	The identifier of the document to which the attachment refers to.	✓
RevDocument2	The revision number of the document to which the attachment refers to. For the delete action, it must be equal to the latest revision number.	This attribute is required for the update and delete 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 created automatically. For the create action, if the attachment already exists, it is updated automatically.	✓
ContentTypeAttach	The attachment content type header.	✓
DestinationAttach	For the read action, the name of the file where you want to receive the attachment.
Operation Parameters
OperationParameters	The list of additional parameters that you can add for the read document 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 Cloudant documentation.
Body
InputFileName	The path and name of the file containing the document or attachment content.
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 HCL Workload Automation

You schedule HCL Workload Automation IBM Cloudant jobs by defining them in job streams. Add the job to a job stream with all the necessary scheduling arguments and submit the job stream.

You can submit jobs by using the Dynamic Workload Console, Application Lab or the conman command line. See Scheduling and submitting jobs and job streams for information about how to schedule and submit jobs and job streams using the various interfaces.

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

Monitoring a job

If the HCL Workload Automation agent stops when you submit the IBM Cloudant job, or while the job is running, the job restarts automatically as soon as the agent restarts.

For information about how to monitor jobs using the different product interfaces available, see Monitoring HCL Workload Automation jobs.

CloudantJobExecutor.properties file

The properties file is automatically generated either when you perform a "Test Connection" from the Dynamic Workload Console in the job definition panels, or when you submit the job to run the first time. Once the file has been created, you can customize it. This is especially useful when you need to schedule several jobs of the same type. You can specify the values in the properties file and avoid having to provide information such as credentials and other information, for each job. You can override the values in the properties files by defining different values at job definition time.

The TWS_INST_DIR\TWS\JavaExt\cfg\CloudantJobExecutor.properties file contains the following properties:

#Cloudant properties
Username=
Password=
AccountText=
DatabaseText=

For a description of each property, see the corresponding job attribute description in Table 1.

Job properties

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

For information about how to display the job properties from the various supported interfaces, see Analyzing the job log. For example, from the conman command line, you can see the job properties by running:

conman sj <job_name>;props

where <job_name> is the IBM Cloudant job name.

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

For information about passing job properties, see Passing job properties from one job to another in the same job stream instance.

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

<?xml version="1.0" encoding="UTF-8"?>
<jsdl:jobDefinition xmlns:jsdl="http://www.abc.com/xmlns/prod/scheduling/1.0/jsdl" 
  xmlns:jsdlcloudant="http://www.abc.com/xmlns/prod/scheduling/1.0/jsdlcloudant" name="CLOUDANT">
  <jsdl:application name="cloudant">
  <jsdlcloudant:cloudant>
  <jsdlcloudant:cloudantParameters>
   		 <jsdlcloudant:Connection>
   		 <jsdlcloudant:UsernameText>cfalcxx</jsdlcloudant:UsernameText>
   		 <jsdlcloudant:PasswordText>xxxxxx00</jsdlcloudant:PasswordText>
   		 <jsdlcloudant:AccountText>54fdc307-1b24-4323-9a91-adc817ac45xx-bluemix
                 </jsdlcloudant:AccountText>
   		 <jsdlcloudant:DatabaseText>mydb</jsdlcloudant:DatabaseText>
   		 </jsdlcloudant:Connection>
   		 <jsdlcloudant:Action>
   		 <jsdlcloudant:ActionButtonGroup>
   		 		 <jsdlcloudant:DocumentRadioButton>
   		 		 <jsdlcloudant:DocumentOperation>DELETE</jsdlcloudant:DocumentOperation>
   		 		 <jsdlcloudant:IdDocument>claudio</jsdlcloudant:IdDocument>
   		 		 <jsdlcloudant:RevDocument/>
   		 		 </jsdlcloudant:DocumentRadioButton>
   		 </jsdlcloudant:ActionButtonGroup>
   		 </jsdlcloudant:Action>
   		 <jsdlcloudant:Body>
   		 <jsdlcloudant:DocumentInputGroup>
   		 		 <jsdlcloudant:InputDocumentButton>
   		 		 <jsdlcloudant:InputDocument/>
   		 		 </jsdlcloudant:InputDocumentButton>
   		 </jsdlcloudant:DocumentInputGroup>
   		 </jsdlcloudant:Body>
  </jsdlcloudant:cloudantParameters>
  </jsdlcloudant:cloudant>
  </jsdl:application>
 </jsdl:jobDefinition>

Job log content

For information about how to display the job log from the various supported interfaces, see Analyzing the job log.

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