Saving report outputs to file system of Cognos Analytics service instance

Manage saving report output files from Cognos Analytics service instance to a file system location.

To be able to save report outputs to a file location, you must take the following actions:

Create a persistent volume clime (PVC) of a required name, storage class and size with create_savetofilesystem_pvc.sh script.
Enable the save to filesystem feature with enable_savetofilesystem.sh script.
Add the location for report output files.

After you enable the feature, you might want to take one of the following optional actions:

Disable saving report outputs with disable_savetofilesystem.sh script.
Manage the size of PVC.

Creating persistent volume claim

To create a PVC of a required name, storage class, and size in the namespace where the Cognos Analytics service instance is installed , use create_savetofilesystem_pvc.sh script.

Synopsis

create_savetofilesystem_pvc.sh [-h] -t tethered_namespace -p pvc_name -s pvc_storageclass -g storage_size

Options

-t tethered_namespace: Tethered namespace or project in which Cognos Analytics instance is provisioned.
-p pvc_name: Name of the PVC.
-s pvc_storageclass: Storage class must be of type Filesystem.
-g storage_size: The size of the storage in Gi.
-h: Prints help to the console and exits.

Example

The following example creates in the namespace cpd-instance a PVC of the name fileoutput, the storage class managed-nfsv3-storage, and the size 200 Gi.

./create_savetofilesystem_pvc.sh -t cpd-instance -p fileoutput -s managed-nfsv3-storage -g 200

Script file

The create_savetofilesystem_pvc.sh script is a file with the following content:

#!/usr/bin/env bash
#
# -----------------------------------------------------------------------------
#         Licensed Materials - Property of IBM
#
#         IBM Cognos Products: ca
#
#         (C) Copyright IBM Corp. 2024
#
#         US Government Users Restricted Rights - Use, duplication or disclosure restricted by
#         GSA ADP Schedule
# -----------------------------------------------------------------------------
#
#
set -e
#set -x
function usage {
    echo "$0: usage: $0 [-h] -t namespace -s storageclass -p persistentvolumeclaim"
    echo "-g storage_size [-v]"
}

function help {
    usage
    echo "-h                    Prints help to the console and exits."
    echo "-t                    Namespace in which Cognos Analytics is provisioned. (required)"
    echo "-s                    Storage class for creating persistent volume. (required)"
    echo "-p                    Name of the persistent volume claim. (required)"
    echo "-g                    Size of the storage, in Gi. (required)"
    echo "-v                    Enables verbose mode"
    echo ""
    exit 0
}

while getopts ":ht:s:p:g:v" opt; do
     case ${opt} in
     h)
        help
        ;;
     t)
        tethered_namespace=$OPTARG
        ;;
     s)
        storage_class=$OPTARG
        ;;
     p)
        pvc_name=$OPTARG
        ;;
     g)
        storage_size=$OPTARG
        ;;
     v)
        verbose_flag="true"
        ;;
     \?)
        usage
        exit 0
        ;;
     esac
done

if [[ -z ${tethered_namespace} ]]; then
    echo "A namespace must be provided"
    help
fi
if [[ -z ${storage_class} ]]; then
    echo "A storage class must be provided"
    help
fi
if [[ -z ${pvc_name} ]]; then
    echo "A persistent volume name must be provided"
    help
fi
if [[ -z ${storage_size} ]]; then
    echo "A storage size must be provided e.g. 100"
    help
fi

#verify oc command is available
command -v oc 2>&1 >/dev/null
if [ $? -ne 0 ]; then
  echo "Openshift Client oc command is not available."
  exit 1
fi
#verify cluster login is valid
echo "Verifying user logged in to cluster:"
oc whoami
if [ $? -ne 0 ]; then
        echo "Please login to cluster first.  Exiting..."
        exit 1
fi

oc cluster-info

echo "Current List of PVC's under namespace: $tethered_namespace"
oc get pvc -n $tethered_namespace

echo "Create PVC ${pvc_name} in ${tethered_namespace}.."

# Create a PVC
cat << EOF | oc create -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ${pvc_name}
  namespace: ${tethered_namespace}
  labels:
    save_to_filesystem_support: true
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: ${storage_size}Gi
  storageClassName: ${storage_class}
  volumeMode: Filesystem
EOF
sleep 10

check_status="Bound"
# Checking status of pvc
for i in {1..12};do
    pvcStatus=$(oc get pvc ${pvc_name} -o jsonpath="{.status.phase}" -n ${tethered_namespace})
    if [[ ${pvcStatus} == ${check_status} ]];then
        echo "pvc status:${pvcStatus} "
        break
    elif [[ ${pvcStatus} == "Pending" ]];then
        echo "pvc status: ${pvcStatus}! please check the PVC:$pvc_name Events.."
        EVENTS=$(oc describe pvc $pvc_name -n ${tethered_namespace} | grep 'Events')
        echo "$EVENTS"
        echo "Execute this command to delete PVC $pvc_name..."
        echo oc delete pvc $pvc_name -n $tethered_namespace
        exit 1
    fi
    sleep 30
done

echo "PVC $pvc_name added..."
oc get pvc $pvc_name -n $tethered_namespace

Enabling the save to filesystem feature

To enable the feature for a PVC in the namespace where the Cognos Analytics instance is provisioned, use enable_savetofilesystem.sh script. The Cognos Analytics containers in the namespace are restarted after enabling the feature.

Synopsis

enable_savetofilesystem.sh [-h] -t tethered_namespace -p pvc_name [-v]

Options

-t tethered_namespace: Tethered namespace or project in which Cognos Analytics instance is provisioned.
-p pvc_name: Name of the PVC.
-v: Enables verbose mode.
-h: Prints help to the console and exits.

Example

The following example enables the save to filesystem feature for PVC of the name fileoutput in Cognos Analytics instances in the namespace cpd-instance

./enable_savetofilesystem.sh -t cpd-instance -p fileoutput

Script file

The enable_savetofilesystem.sh script is a file with the following content:

#!/usr/bin/env bash
#
# -----------------------------------------------------------------------------
#         Licensed Materials - Property of IBM
#
#         IBM Cognos Products: ca
#
#         (C) Copyright IBM Corp. 2024
#
#         US Government Users Restricted Rights - Use, duplication or disclosure restricted by
#         GSA ADP Schedule
# -----------------------------------------------------------------------------
#
#
set -e
#set -x
function usage {
    echo $0: usage: $0 [-h] -t tethered_namespace -p persistentvolumeclaim [-v]
}

function help {
    usage
    echo "-h                    Prints help to the console and exits."
    echo "-t                    Namespace in which Cognos Analytics is provisioned. (required)"
    echo "-p                    Name of the persistent volume claim. (required)"
    echo "-v                    Enables verbose mode."
    echo ""
    exit 0
}

while getopts ":ht:p:v" opt; do
     case ${opt} in
     h)
        help
        ;;
     t)
        tethered_namespace=$OPTARG
        ;;
     p)
        pvc_name=$OPTARG
        ;;
     v)
        verbose_flag="true"
        ;;
     \?)
        usage
        exit 0
        ;;
     esac
done

if [[ -z ${tethered_namespace} ]]; then
    echo "A namespace must be provided"
    help
fi
if [[ -z ${pvc_name} ]]; then
    echo "A pvc name must be provided"
    help
fi

#verify oc command is available
command -v oc 2>&1 >/dev/null
if [ $? -ne 0 ]; then
  echo "Openshift Client oc command is not available."
  exit 1
fi
#verify cluster login is valid
echo "Verifying user logged in to cluster:"
oc whoami
if [ $? -ne 0 ]; then
        echo "Please login to cluster first.  Exiting..."
        exit 1
fi
oc cluster-info

echo "Checking the PVC $pvc_name is in a Bound State..."
check_status="Bound"
# Checking status of pvc
for i in {1..12};do
    pvcStatus=$(oc get pvc ${pvc_name} -o jsonpath="{.status.phase}" -n ${tethered_namespace})
    if [[ ${pvcStatus} == ${check_status} ]];then
        echo "pvc status:${pvcStatus} "
        break
    elif [[ ${pvcStatus} == "Pending" ]];then
        echo "PVC status: ${pvcStatus}! Please check the PVC $pvc_name Events..."
        EVENTS=$(oc describe pvc $pvc_name -n ${tethered_namespace} | grep 'Events')
        echo "$EVENTS"
        echo "Execute this command to delete PVC $pvc_name..."
        echo oc delete pvc $pvc_name -n $tethered_namespace
        exit 1
    fi
    sleep 30
done

echo "Patching the CR to update the pvc...."
cr_name=$(oc -n ${tethered_namespace} get caserviceinstance --no-headers \
-o custom-columns=NAME:.metadata.name)
if [[ -z ${cr_name} ]]; then
    echo "Unable to find CAServiceInstance CR for namespace: ${tethered_namespace}"
    help
fi
echo "Adding cogSaveToFilesystem pvc name: ${pvc_name} to the Custom Resource ${cr_name}..."
oc patch caserviceinstance ${cr_name} --type merge \
-p "{\"spec\":{\"cogSaveToFilesystemPVCName\":\"${pvc_name}\"}}" -n ${tethered_namespace}
sleep 20

check_status="Completed"
# Checking status of ca reconcile action
for i in {1..240};do
    caStatus=$(oc get caserviceinstance ${cr_name} \
    -o jsonpath="{.status.caStatus}" -n ${tethered_namespace})
    if [[ ${caStatus} == ${check_status} ]];then
        echo "ca ${check_status} Successfully"
        break
    elif [[ ${caStatus} == "Failed" ]];then
        echo "ca ${caStatus}!"
        echo "Remove cogSaveToFilesystemPVCName value from custom resource to revert change"
        oc patch caserviceinstance ${cr_name} -n ${tethered_namespace} --type=json \
        --patch "[{"op": "remove", "path":"/spec/cogSaveToFilesystemPVCName"}]"
        exit 1
    fi
    echo "ca Status: ${caStatus}"
    sleep 30
done

Adding location for report output files

The instance administrator must now configure the file location.

The report output files are saved to this location when you select Save report as an external file as the report delivery method when you run or schedule a report.

For details, see the step 3 of the procedure in the Saving report output files outside of IBM Cognos software topic of the Cognos Analytics documentation.

Disabling the save to filesystem feature

To disable the feature for a PVC in the namespace where the Cognos Analytics instance is provisioned, use disable_savetofilesystem.sh script. The Cognos Analytics containers in the namespace are restarted after disabling the feature.

Synopsis

disable_savetofilesystem.sh [-h] -t tethered_namespace [-v]

Options

-t tethered_namespace: Tethered namespace or project in which Cognos Analytics instance is provisioned.
-v: Enables verbose mode.
-h: Prints help to the console and exits.

Example

The following example disables the save to filesystem feature in Cognos Analytics instances in the namespace cpd-instance

./disable_savetofilesystem.sh -t cpd-instance

Script file

The disable_savetofilesystem.sh script is a file with the following content:

#!/usr/bin/env bash
#
# -----------------------------------------------------------------------------
#         Licensed Materials - Property of IBM
#
#         IBM Cognos Products: ca
#
#         (C) Copyright IBM Corp. 2024
#
#         US Government Users Restricted Rights - Use, duplication or disclosure restricted by
#         GSA ADP Schedule
# -----------------------------------------------------------------------------
#
#
set -e
#set -x
function usage {
    echo $0: usage: $0 [-h] -t tethered_namespace -p persistentvolumeclaim [-v]
}

function help {
    usage
    echo "-h                    Prints help to the console and exits."
    echo "-t                    Namespace in which Cognos Analytics is provisioned. (required)"
    echo "-v                    Enables verbose mode."
    echo ""
    exit 0
}

while getopts ":ht:v" opt; do
     case ${opt} in
     h)
        help
        ;;
     t)
        tethered_namespace=$OPTARG
        ;;
     v)
        verbose_flag="true"
        ;;
     \?)
        usage
        exit 0
        ;;
     esac
done

if [[ -z ${tethered_namespace} ]]; then
    echo "A namespace must be provided"
    help
fi

#verify oc command is available
command -v oc 2>&1 >/dev/null
if [ $? -ne 0 ]; then
  echo "Openshift Client oc command is not available."
  exit 1
fi
#verify cluster login is valid
echo "Verifying user logged in to cluster:"
oc whoami
if [ $? -ne 0 ]; then
        echo "Please login to cluster first.  Exiting..."
        exit 1
fi
oc cluster-info

echo "Verify CR in namespace to remove the cogSaveToFilesystemPVCName ..."
cr_name=$(oc -n ${tethered_namespace} get caserviceinstance --no-headers \
-o custom-columns=NAME:.metadata.name)
if [[ -z ${cr_name} ]]; then
    echo "Unable to find CAServiceInstance CR for namespace: ${tethered_namespace}"
    help
fi
echo "Patching custom resource to revert changes done..."
oc patch caserviceinstance ${cr_name} -n ${tethered_namespace} --type=json \
--patch "[{"op": "remove", "path": "/spec/cogSaveToFilesystemPVCName"}]"
sleep 20

check_status="Completed"
# Checking status of ca reconcile action
for i in {1..240};do
    caStatus=$(oc get caserviceinstance ${cr_name} \
    -o jsonpath="{.status.caStatus}" -n ${tethered_namespace})
    if [[ ${caStatus} == ${check_status} ]];then
        echo "ca ${check_status} Successfully"
        break
    elif [[ ${caStatus} == "Failed" ]];then
        echo "ca ${caStatus}!"
        exit 1
    fi
    echo "ca Status: ${caStatus}"
    sleep 30
done

Managing PVC size

You can enlarge PVC for storing report output files from Cognos Analytics instance service by completing the following procedure:

In the same namespace, create a second PVC with the create_savetofilesystem_pvc.shscript.
Run the enable_savetofilesystem.sh script with a new name for this PVC.
Optional: If you want to copy the old PVC content into the new PVC, create a job in the namespace that mounts the old and the new PVC and copies the content.
Optional: If you do not want to keep the report output on the old PVC, delete this one.