trigger(triggerName)

Use this method to initiate a trigger-based schedule in response to an external occurrence.

For example, you may want to ensure that reports are run every Wednesday after the reporting database has been backed up. After the backup is completed, a script using this method triggers the report to run.

To schedule execution of an object based on a trigger, do the following:

  1. Create an instance of the bibus » schedule class for the object.

  2. Set the type property to trigger.

  3. Set the triggerName property to the name of the external occurrence.

  4. Save the schedule.

The event management service:

  • will return a fault if the triggerName sent in on a trigger request is null or zero length

  • executes only reports that the user can see in Content Manager

  • asks Content Manager for a list of schedules that have a matching triggerName and are active

  • returns the number of schedules that were activated by this method

  • runs the task associated with the schedule under the user specified by the bibus » schedule » credential property

Use of this method requires:

Signatures

Java and Apache Axis
 
public  int  trigger(java.lang.String  triggerName) 
C# .NET
 
public  int  trigger(string  triggerName) 
Example: Using the trigger(triggerName) Method with the Event Management Service in Java

The following Java code snippet demonstrates how to use the event » trigger(triggerName) method with the event management service.

To see this code in context, view the Java sample EventTrigger/Trigger.java. For more information about the samples, see Code samples and language-specific coding practices.

 
return  eventService.trigger(triggerName); 
 

References

Part of the following method sets:
Implemented by the following services:

The services that implement the trigger method, along with the associated SOAP actions, are listed in the following table.

Table 1. Services implementing the trigger method.

Service

SOAP Action
eventManagementService

http://www.ibm.com/xmlns/prod/cognos/eventManagementService/201404/

What's new

New in Version 10.1.0 — Administration Capabilities for Background Job Queue Maintenance

This method now checks for the canUseMonitorActivityTool value capability instead of the canUseAdministrationPortal value capability.

Input parameters

Use the following parameters when calling this method.

triggerName

Specifies the name of the external occurrence. Tasks associated with schedules that have a matching value for the bibus » schedule » triggerName property are queued for execution.

This parameter can also be substituted with a string similar to a command URI:

<trigger-name>?f=<folder-search-path>&f=<folder-search-path>& ... 
  &f=<folder-search-path> 

For example:

"TDAILY?f=/content/folder[@name='Customer A']&f=/content/folder[@name='Customer B']" 

The scheduler interprets the arguments from left to right, obtains the list of runnable objects associated with each folder and triggerName, and queues the objects for execution.

An SDK application cannot control the order of execution within a folder, only the order that each folder is executed in for a particular trigger name.

Each trigger requires its own SDK call, but each triggerName string may contain one or more folders.

For example, an SDK application can call this method with a partial list of folders when it detects that the data refresh is late, and submit additional folders for execution as the appropriate content is delivered. The SDK application would have the option to:

  • Call the trigger method without a list of folder paths.

    All schedules associated with this trigger would be executed immediately.

  • Call the trigger with a prioritized list of folder paths using the trigger execution URI string.

    Only the objects residing under the folder list would be executed in the specified order. The application must ensure that all folders are specified using single or multiple calls to the method.

There is no context kept by the call. For example, if a call is made with a list of selected folders and a second call only specifies a trigger by name, all runnable objects associated with the trigger are executed, even those that were executed in the previous prioritized method call.

Do not use the question mark character "?" unless you are specifying a list of folder search path strings. Doing so may cause unpredictable results as an attempt will be made to interpret anything after the question mark as a search path.

This argument

  • is of type string

    is encoded as type xs:string

Return values

This method returns the following values.

result

Returns the number of schedules that were activated.

This result

  • is of type int

    is encoded as type xs:int