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

    All Methods Instance Methods Abstract Methods
    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
    `Id` | `launchLogCollector(LaunchLogCollectorOptions options)` Launch Log Collector tool
    `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

    - #### launchLogCollector

          Id launchLogCollector(LaunchLogCollectorOptions options)

      Launch Log Collector tool
      Parameters:
        `options` - : launch options
      Returns:
        id of the long running process

Licensed Materials - Property of IBM
OpenPages with Watson (PID: 5725-D51)
© Copyright IBM Corporation 2013, 2021. All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.