Example - schedule a report

Schedule a report to run at a specific time or at recurring times. For example, you may need to run a report daily or during off-peak hours.

To schedule a report using the Software Development Kit, create a schedule object and set the appropriate values for its properties. Then, use the add(parentPath, objects, options) method to add it to the content store.

These code examples show you how to schedule a report. For example, some groups in your organization may need the data in a report updated by the minute. To meet this need, you set up a report view, schedule the report to run each minute, and then verify that it is properly scheduled.

Methods

You can use the add(parentPath, objects, options) method to schedule a report.

See the Methods chapter in the Software Development Kit Developer Guide for the permissions and capabilities required for this method.

Java code

To see the code in context, view the following sample:

installation_location/sdk/vb/Scheduler/NewScheduler.java

The following Java™ code snippets demonstrate how you can schedule a report.

Steps for a Java program

Ensure that the currently logged-on account has a credential and obtain a reference to that credential.

if (! Credentials.hasCredential(connection))
{
	Credentials newCred = new Credentials();
	newCred.addCredential(connection);
}
Account logonInfo = Logon.getLogonAccount(connection);
Credential credential = new Credential();
StringProp credentialPath = new StringProp();
String credentialPathString = logonInfo.getSearchPath().getValue();
credentialPathString = credentialPathString + "/credential[@name='Credential']";
credentialPath.setValue(credentialPathString);
credential.setSearchPath(credentialPath);
BaseClassArrayProp credentials = new BaseClassArrayProp();
credentials.setValue(new BaseClass[] {credential} );

Set the schedule start date and time.


public DateTimeProp setScheduleStartDate(Calendar startOnDate)
{
	DateTimeProp startDate = new DateTimeProp();
	//If start date not passed set to today/now
	if (startOnDate != null)
		startDate.setValue(startOnDate);
	else
		startDate.setValue(Calendar.getInstance());

	return startDate;
}

Set the schedule end date and time.


public DateTimeProp setScheduleEndDate(
	Calendar endOnDate,
	String endOnTime)
{
	DateTimeProp endDate = new DateTimeProp();
	if (endOnTime.compareToIgnoreCase("onDate") == 0)
		if (endOnDate != null)
		{
			endDate.setValue(endOnDate);
		}
		else
			System.out.println(
				"Parameter endOnTime cannot be onDate if no enddate provided");
	return endDate;
}

public NmtokenProp setScheduleEndTime(String endOnTime)
{
	NmtokenProp endTime = new NmtokenProp();
	if (endOnTime != null)
	{
		endTime.setValue(endOnTime);
	}
	else
		System.out.println(
			"Parameter endOnTime cannot be null! Options: indefinite or onDate");
	return endTime;
}

Assign the current user as the owner.


BaseClass[] owners = new BaseClass[] { Logon.getLogonAccount(connection) };
BaseClassArrayProp ownersProp = new BaseClassArrayProp();
ownersProp.setValue(owners);

Set the options.


OptionArrayProp roap = new OptionArrayProp();
String reportPath = report.getBaseClassObject().getSearchPath().getValue();

//Set options
roap.setValue(
	this.setSchedulerOptions(
		outFormat,
		delivery,
		reportPath,
		printerName,
		saveasName,
		pageOrientation,
		paper,
		emails,
		connection));
...
RunOptionSaveAs saveAs = new RunOptionSaveAs();
MultilingualToken[] obj = new MultilingualToken[1];

//Set the name of the reportView
obj[0] = new MultilingualToken();
obj[0].setLocale("en-us");

//If no name provided use default
if (saveasName != null)
{
	obj[0].setValue(saveasName);
}
else
{
	obj[0].setValue("View of Report " + reportPath);
}

//Save the object as report view with name saveasName
saveAs.setName(RunOptionEnum.saveAs);
saveAs.setObjectClass(ReportSaveAsEnum.reportView);
saveAs.setObjectName(obj);
saveAs.setParentSearchPath(csh.getParentPath(connection, reportPath));

Set the properties of the schedule object and add it to the report.

newSchedule.setActive(isActive);
newSchedule.setCredential(credentials);
newSchedule.setEndDate(this.setScheduleEndDate(endOnDate, endOnTime));
newSchedule.setEndType(this.setScheduleEndTime(endOnTime));
newSchedule.setOwner(ownersProp);
newSchedule.setParameters(pv);
newSchedule.setOptions(roap);
newSchedule.setStartDate(this.setScheduleStartDate(startOnDate));
newSchedule.setType(howOften);

//  add the schedule to the report
AddOptions ao = new AddOptions();
ao.setUpdateAction(UpdateActionEnum.replace);
BaseClass newBc = connection.getCMService().add(
	new SearchPathSingleObject(reportPath),
	new BaseClass[] { newSchedule },
	ao)[0];

C# code

To see the code in context, view the following sample:

installation_location/sdk/csharp/Schedule/Schedule.cs

Before you can use this sample, you must create a credential object for the account that you will use to run the sample. For more information about creating credentials, see the Administration and Security Guide.

The following C# code snippets demonstrate how you can schedule a report.

Steps for a C# program

Ensure that the currently logged-on account has a credential and obtain a reference to that credential.


//get the credential for the schedule
credential schedCred = connection.getCredential();
baseClassArrayProp credentials = new baseClassArrayProp();
credentials.value = new baseClass[] {schedCred};
newSched.credential = credentials;

Set the schedule start and end dates and times.

// set schedule time to now + 2 minutes
System.DateTime startTime = new DateTime();
startTime = DateTime.Now;
startTime = startTime.AddMinutes(2);
dateTimeProp schedStartTime = new dateTimeProp();
schedStartTime.value = startTime;
newSched.startDate = schedStartTime;

// set schedule end time to now + 5 minutes
System.DateTime endTime = new DateTime();
endTime = DateTime.Now;
endTime = endTime.AddMinutes(5);
dateTimeProp schedEndTime = new dateTimeProp();
schedEndTime.value = endTime;
newSched.endDate = schedEndTime;

// set the schedule end type
nmtokenProp endType = new nmtokenProp();
endType.value = "onDate";
newSched.endType = endType;

Assign the current user as the owner.

//set the owner
baseClassArrayProp ownersProp = new baseClassArrayProp();
baseClass[] owners = new baseClass[]
	{ SamplesConnect.getLogonAccount(connection) };
ownersProp.value = owners;
newSched.owner = ownersProp;

Set the options.

//Set the name of the reportView
multilingualToken[] reportViewName = new multilingualToken[1];
reportViewName[0] = new multilingualToken();
reportViewName[0].locale = "en-us";
reportViewName[0].value = "View of Report " +
	reportToSchedule.baseclassobject.defaultName.value;

//Save the output as report view with name saveasName
runOptionSaveAs saveAs = new runOptionSaveAs();
saveAs.name = runOptionEnum.saveAs;
saveAs.objectClass = reportSaveAsEnum.reportView;
saveAs.objectName = reportViewName;
saveAs.parentSearchPath = reportToSchedule.parentPath.value;

//Turn off prompting
runOptionBoolean prompt = new runOptionBoolean();
prompt.name = runOptionEnum.prompt;
prompt.value = false;

//set the output format
runOptionStringArray format = new runOptionStringArray();
format.name = runOptionEnum.outputFormat;
format.value = new string[] { "HTML" };

//put the run options where they need to go
runOption[] schedRunOptArr = new runOption[3];
schedRunOptArr[0] = saveAs;
schedRunOptArr[1] = prompt;
schedRunOptArr[2] = format;

runOptionArrayProp schedRunOptions = new runOptionArrayProp();
schedRunOptions.value = schedRunOptArr;
newSched.runOptions = schedRunOptions;

Set the properties of the schedule object and add it to the report.

//mark the schedule as active
booleanProp isActive = new booleanProp();
isActive.value = true;
newSched.active = isActive;

//Set the type of schedule
cognosdotnet_10_2.nmtokenProp scheduleType = new nmtokenProp();
scheduleType.value = "daily";
newSched.type = scheduleType;
		
//make the schedule for every x minutes
nmtokenProp period = new nmtokenProp();
period.value = "minute";
newSched.dailyPeriod = period;

//set that every x minutes to be every 1 minute
positiveIntegerProp runFreqProp = new positiveIntegerProp();
runFreqProp.value = "1";
newSched.everyNPeriods = runFreqProp;
...
searchPathSingleObject reportSearchPath = new searchPathSingleObject();
reportSearchPath.Value =
	((baseClass) reportToSchedule.baseclassobject).searchPath.value;
//  add the schedule to the report
addOptions ao = new addOptions();
ao.updateAction = updateActionEnum.replace;
baseClass newBc = connection.CBICMS.add(
	reportSearchPath,
	new baseClass[] { newSched },
	ao)[0];

Explanation

To create the schedule, you first create a schedule object and specify values for its properties. The following are examples of the properties that may be specified:

active
credential
dailyPeriod
endDate
endType
everyNPeriods
options
startDate

See the description of the schedule class in the chapter on classes in the Software Development Kit Developer Guide for a complete list and description of the properties.

If the report contains prompts, you must also specify parameters in the parameters property.

The schedule in a schedule array is passed to the add(parentPath, objects, options) method and the schedule is created in the content store.

Steps when writing your own programs

Create an array of schedule objects.
Create a new schedule object.
Create a new addOptions object.
Create a dateTimeProp object for the starting date and time for the schedule object, and set its value to the required start date and time. Assign this dateTimeProp object to the startDate property of the schedule.
Build an array of option objects for the schedule object. These options will apply whenever the scheduled report runs. Assign this array to the value property of the options property of the schedule object.
Set the values for the other properties of the schedule object.
Add the schedule object to the schedule array.
Set desired values for the properties of the addOptions object.
Call the add(parentPath, objects, options) method, passing the search path, the schedule array, and the addOptions object as parameters.