Creating Schedulable Program Objects

As the depth and breadth of business intelligence (BI) platforms like Crystal Enterprise grow within organizations today, one of the key challenges is the interoperability of the core BI platform with the rest of the surrounding infrastructure. There are many services that the BI platform might need to work with such as ETL tools, databases/data warehouses, Web servers, portal servers, and security and directory servers. One of the ways that Crystal Enterprise can work with these external technologies is through Program Objects.

A Program Object is a small program or link to a program published as a standard object to Crystal Enterprise. It has its own name, location in the folder structure, security permission, and all the other attributes youd expect from a standard Crystal Enterprise object. From a programmatic perspective, it is represented by an InfoObject. Generally Program Objects are only scheduled, not viewed on-demand. They are processed by the Program Job Server instead of the Report Job Server. Figure 36.4 shows creating a Program Object from the Crystal Management Console.

There are three types of programs that can be run via a Program Object: an executable, a script file, or a Java program. When creating a Program Object, you simply point to the location of the file. When creating the scheduled job, you can specify arguments to the program. The types of executable files supported are .exe, .bat, and .sh. The types of script files supported are .vbs and .js. The more interesting type of Program Object is a Java program. To write a Java program that can be scheduled within Crystal Enterprise, you must implement the IProgramBase interface found in the com.crystaldecisions.sdk.plugin. desktop.program package. This interface only has a single method called run. It receives as arguments to the method: a valid IEnterpriseSession, a valid IInfoStore, and a String array consisting of the programs arguments as defined at schedule time. This is useful because you can use these objects to gain access to Crystal Enterprise without having to pass in credentials. Listing 36.1 provides an example Java Program Object that when scheduled, accepts a username as an argument and deletes all object instances that are owned by that user (in other words, all the objects that the user scheduled).

Listing 36.1. DeleteInstances.java

import com.crystaldecisions.sdk.plugin.desktop.program.IProgramBase; import com.crystaldecisions.sdk.framework.IEnterpriseSession; import com.crystaldecisions.sdk.exception.SDKException; import com.crystaldecisions.sdk.occa.infostore.*; import java.util.Date; public class DeleteInstances implements IProgramBase { public void run(IEnterpriseSession session, IInfoStore iStore, String[] args) throws SDKException { String query; IInfoObjects infoObjects; Date now = new Date(); query = "SELECT SI_ID, SI_NAME, SI_ENDTIME FROM CI_INFOOBJECTS WHERE" + " SI_PROGID = CrystalEnterprise.Report AND " + "SI_INSTANCE_OBJECT=1 AND SI_OWNER = " + args[0] + ""; System.out.println("Executing at " + now); System.out.println("Deleting all instances owned by " + args[0] + " on " + session.getCMSName()); System.out.println("query: " + query); infoObjects = iStore.query(query); System.out.println(infoObjects.getResultSize() + " instance(s) found for " + args[0] + " on " + session.getCMSName()); if (infoObjects.getResultSize() > 0) { int infoObjectsReturned = infoObjects.getResultSize(); for (int i=infoObjectsReturned-1; i > -1; i--) { IInfoObject infoObject = (IInfoObject)infoObjects.get(i); IProperty props = infoObjects.properties(); System.out.println((infoObjectsReturned i + 1) + ".) Deleting Instance #" + infoObject.getID() + " (" + infoObject.getTitle() + " - " + props.getProperty("SI_ENDTIME").getValue() + ")" ); infoObjects.delete(infoObject); } System.out.println("Committing Delete Action"); iStore.commit(infoObjects); } System.out.println("Exiting"); } }

Because a Java Program Object needs to implement an interface defined in the Crystal Enterprise Java libraries, you need to include those libraries in the classpath when compiling the program. The specific files you need to reference are

• cesession.jar
• ceplugins.jar
• cecore.jar
• celib.jar

These and the rest of the Crystal Enterprise Java libraries can be found in the following directory:

Program FilesCommon FilesCrystal Decisions2.5javalib

Figure 36.5 shows the output of scheduling the DeleteInstances Java Program Object and passing in Administrator as the username to delete instances for.

There are many uses for Java Program Objects. Because the implementation for the program is defined by the developer the only limits are the creativity in which it is used. Some typical examples of Program Objects are

• Performing maintenance-like actions on the Crystal Enterprise system, such as deleting unused instances, archiving instances to another location, creating auditing snapshots, and so on.
• Running external applications such as database or data warehouse loads, queries, extraction transformation and loading (ETL) tools.
• Scheduling arbitrary programs to run such as virus checkers.

Performing data warehouse loads can be a great use of a Program Object. In the previous chapter you learned how to create a scheduled report job (or scheduled report package job) that waited for an event to be triggered before it ran. If you were to create a Program Object that launched a data warehouse load, you could create a "schedule event" attached to the Program Object. The end result would be that a report or collection of reports would wait until a successful execution of the data warehouse load was done before running the report off that warehouse. This ensures the reports don run too early before the warehouse load is complete and also ensures that if the warehouse load fails, the reports don run at all.