com.ibm.openpages.api.service

Interface IApplicationService

public interface IApplicationService

Interface for higher-level OpenPages application-specific functionality. For all operations, a user performing an operation should have necessary permissions to do so. Otherwise, an exception message is returned.

Method Summary

Modifier and Type	Method and Description
java.util.List<IGRCObject>	copyToParent(Id parentObjectId, java.util.List<Id> childrenToCopy, CopyObjectOptions copyOptions) Copies one or more GRCObjects to a parent GRCObject based on the CopyObjectOptions and returns the copies made for each of the childrenToCopy that are specified.
IReportParameters	getParametersForReport(java.lang.String reportPath) Retrieve IReportParameters that contains all parameters a report expects for inputs.
java.io.InputStream	invokeCognosReport(java.lang.String reportPath, CognosOutputFormat format, IReportParameters parameters) Invokes an IBM Cognos Report programatically and the resulting output file is returned in a format that can be read by the returned InputStream.
ICognosReportRowReader	invokeCognosRowReport(java.lang.String reportPath, IReportParameters params) You cannot produce a report in CSV or XML format if you have more than one query defined in the report, unless the additional queries are used for prompts.
java.lang.String	invokeReportFragment(Id id, IFieldDefinition field) Invoke report fragment on a given object and return the report fragment as a String
void	lockGRCObject(Id grcObject) Apply a direct lock to specified GRCObject.
void	moveGRCObject(Id parentObjectId, java.util.List<Id> childrenToMove, MoveObjectOptions moveOptions) Moves one or more GRCObjects to a new parent GRCObject.
void	removeAllLocks(Id grcObject) Removes all locks, direct and inherited, for a tree of GRC Objects starting from the specified grcObject.
void	unlockGRCObject(Id grcObject) Unlock a locked GRCObject.

Method Detail

moveGRCObject

void moveGRCObject(Id parentObjectId,
                   java.util.List<Id> childrenToMove,
                   MoveObjectOptions moveOptions)

Moves one or more GRCObjects to a new parent GRCObject. Updates the folder location of the moved children to the parent's folder path, disassociates the children from the previous primary parent, and creates an association to the new parent. Any primary descendants of the children will remain associated with the moved children, their folder locations will also be updated. Secondary association descendents will not be moved. The behavior of which descendants will be moved is configurable through the MoveObjectOptions parameter.

Example:
Move a Risk Assessment (RA1) from entity E1 to entity E2. The Risk Assessment is a parent of multiple children Risks. The hierarchy looks like:

 E1
 |--RA1
    |--R1
    |--R2
    |--etc...
 E2
 

The folder paths for RA1 would similarly be:

 /Risk Assessments/E1/RA1
 /Risks/E1/R1
 /Risks/E1/R2
 etc...
 

After the move, the hierarchy looks like:

 E1
 E2
 |--RA1
    |--R1
    |--R2
    |--etc...
 

The folder paths are updated respectively (assuming R1 and R2 are primary children of RA1):

 /Risk Assessments/E2/RA1
 /Risks/E2/R1
 /Risks/E2/R2
 etc...
 

Restrictions:
The method is transactional. Any errors will roll-back all changes.
Moving a parent under one of it's own children will result in an exception.
The arguments must be IGRCObjects, folders cannot be moved. The children Ids must be of Types that have a parent association enabled with the Parent Object.
Note: To update any IGRCObjects in your code for moved children that you previously retrieved, you must retrieve them again after the move.

Parameters:

parentObjectId - (required) target Parent GRCObject's Id

childrenToMove - (required) Ids of Child GRCObjects to move to the new parent specified by parentObjectId

moveOptions - (required) options to control behavior. For default options, use MoveObjectOptions.getDefaultOptions()

copyToParent

java.util.List<IGRCObject> copyToParent(Id parentObjectId,
                                        java.util.List<Id> childrenToCopy,
                                        CopyObjectOptions copyOptions)

Copies one or more GRCObjects to a parent GRCObject based on the CopyObjectOptions and returns the copies made for each of the childrenToCopy that are specified.

Restrictions:
The method is transactional. Any errors will roll-back all changes.
Copying a parent under one of it's own children will result in an exception.
The arguments must be IGRCObjects, folders cannot be copied with this call. The children Ids must be of Types that have a parent association enabled with the Parent Object.
Descendent children of the copies are not returned and will need follow up retrievals or queries.

Parameters:

parentObjectId - (required) target Parent GRCObject's Id

childrenToCopy - (required) Ids of root child GRCObjects to copy to the new parent specified by parentObjectId

copyOptions - (required) configures behavior of the copy; for example, the included child types

Returns:

list of newly copied objects

lockGRCObject

void lockGRCObject(Id grcObject)

Apply a direct lock to specified GRCObject. Only GRCObjects can be locked. Applies the Settings from Lock Child Types to apply inherited locks for any children. Users performing this operation must have necessary permissions to lock the object.

Parameters:

grcObject - (required) object to lock

unlockGRCObject

void unlockGRCObject(Id grcObject)

Unlock a locked GRCObject. Any inherited locks on children of this GRCObject will be removed automatically. If the GRC Object is locked with inherited locks as well a direct lock, the inherited locks will not be removed.

Parameters:

grcObject - (required) locked object to unlock

See Also:

removeAllLocks(Id)

removeAllLocks

void removeAllLocks(Id grcObject)

Removes all locks, direct and inherited, for a tree of GRC Objects starting from the specified grcObject. Any locks on the tree of the GRC Objects beneath the root will be removed.

Parameters:

grcObject - (required) root object to search for locks to be removed

invokeCognosReport

java.io.InputStream invokeCognosReport(java.lang.String reportPath,
                                       CognosOutputFormat format,
                                       IReportParameters parameters)

Invokes an IBM Cognos Report programatically and the resulting output file is returned in a format that can be read by the returned InputStream.

Parameters:

reportPath - (required) path to report in the Cognos product. For a report in 'Public Reports/MY_FOLDER/My Report Name' use: "/content/folder[@name='MY_FOLDER']/report[@name='My Report Name']"

format - (required) output format to be returned from supported CognosOutputFormats

parameters - (optional) IReportParameters containing input parameters for any report prompts where key is the exact prompt name and value is a String[] containing the input values. For example, if your report contains a filter on Reporting Period Id (e.g. [REPORTING_PERIOD_ID] = ?rpid?), to pass a parameter value to this prompt, you would retrieve an instance of the IReportParameters object for that report and put the value IReportParameters parameters = applicationService.getParametersForReport(reportPath); parameters.setParameterValue("rpid", "-1" );
If parameters are not required, you may pass a null value instead.

Returns:

initialized InputStream containing the data for the Cognos report output of requested format.

getParametersForReport

IReportParameters getParametersForReport(java.lang.String reportPath)

Retrieve IReportParameters that contains all parameters a report expects for inputs.

Parameters:

reportPath - (required) path to report in Cognos. For a report in 'Public Reports/MY_FOLDER/My Report Name' use: "/content/folder[@name='MY_FOLDER']/report[@name='My Report Name']"

Returns:

IReportParameters object containing all found reports

invokeCognosRowReport

ICognosReportRowReader invokeCognosRowReport(java.lang.String reportPath,
                                             IReportParameters params)

You cannot produce a report in CSV or XML format if you have more than one query defined in the report, unless the additional queries are used for prompts. As such, only the master query shows up in the XML.

To invoke a Cognos Report output in a tabular format (for programmatically reading the results one row at a time), use the ICognosReportRowReader.

Parameters:

reportPath - (required) path to report in IBM Cognos. For a report in 'Public Reports/MY_FOLDER/My Report Name' use: "/content/folder[@name='MY_FOLDER']/report[@name='My Report Name']"

parameters - (optional) IReportParameters containing input parameters for any report prompts where key is the exact prompt name and value is a String[] containing the input values. For example, if your report contains a filter on Reporting Period Id (e.g. [REPORTING_PERIOD_ID] = ?rpid?), to pass a parameter value to this prompt, you would retrieve an instance of the IReportParameters object for that report and put the value IReportParameters parameters = applicationService.getParametersForReport(reportPath); parameters.setParameterValue("rpid", "-1" );
If parameters are not required, you may pass a null value instead.

Returns:

initialized ICognosReportRowReader for the Cognos report output.

An example consuming the ICognosReportRowReader data:
//iterate over rows
for (ICognosReportRow row : csvRowReader) { //iterate over columns in the row
for (ICognosReportColumnValue value : row) { ... } //optionally access columns directly, you can use either column index or name //row.getColumnValue(1); }

invokeReportFragment

java.lang.String invokeReportFragment(Id id,
                                      IFieldDefinition field)

Invoke report fragment on a given object and return the report fragment as a String

Parameters:

id - (required) The Id of the object to retrieve

field - (required) the report fragment field

Returns:

report fragment