One Identity Safeguard for Privileged Sessions 6.0.2 - REST API Reference Guide

Indexer policies

Indexer policies allow you to configure the Optical Character Recognition (OCR) engine of SPS, and specify which languages it should use. Only graphical protocols (RDP, Citrix ICA, VNC) are affected.

If you specify the languages manually, note the following:

• Specifying only one language provides the best results in terms of performance and precision.

• The English language is always detected along with the non-English languages that you have configured. However, if you want the OCR to only recognize the English language, you have to select it from the list of languages.

• There are certain limitations in the OCR engine when recognizing languages with very different character sets. For this reason, consider the following:

  • When selecting Asian languages (Simplified Chinese, Traditional Chinese, Korean), avoid adding languages that use the Latin alphabet.

  • When selecting the Arabic language, avoid selecting any other languages.

  • The Thai language is currently not supported. If you are interested in using SPS to index Thai texts, contact our Sales Team.

URL

GET https://<IP-address-of-SPS>/api/configuration/policies/indexing

Cookies

Sample request

The following command lists the available indexer policies.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/indexing

The following command displays a specific indexer policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/indexing/<id-of-the-policy>

Response

The following is a sample response received when querying the /api/configuration/policies/indexing/ endpoint.

For details of the meta object, see Message format.

{
    "items": [
        {
            "key": "-50000",
            "meta": {
                "href": "/api/configuration/policies/indexing/-50000"
            }
        },
        {
            "key": "13442970955825a89b55e46",
            "meta": {
                "href": "/api/configuration/policies/indexing/13442970955825a89b55e46"
            }
        }
    ],

    "meta": {
        "first": "/api/configuration/policies/audit_policies",
        "href": "/api/configuration/policies/indexing",
        "last": "/api/configuration/policies/usermapping_policies",
        "next": "/api/configuration/policies/ldap_servers",
        "parent": "/api/configuration/policies",
        "previous": "/api/configuration/policies/credentialstores",
        "remaining_seconds": 599,
        "transaction": "/api/transaction"
    }
}

A sample response when querying a specific indexer policy:

{
    "body": {
        "index": {
            "command": true,
            "keyboard": false,
            "mouse": false,
            "screen_content": false,
            "window_title": true
        },
        "name": "english-german-russian",
        "ocr": {
            "accuracy": "accurate"
            "custom_languages": {
                "enabled": true,
                "languages": [
                    "eng",
                    "deu",
                    "rus"
                ]
            }
        }
    },
    "key": "-50000",
    "meta": {
        "first": "/api/configuration/policies/indexing/-50000",
        "href": "/api/configuration/policies/indexing/-50000",
        "last": "/api/configuration/policies/indexing/-50000",
        "next": null,
        "parent": "/api/configuration/policies/indexing",
        "previous": null,
        "remaining_seconds": 599,
        "transaction": "/api/transaction"
    }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Add an indexing policy

To add an indexing policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new indexing policy.

   You can find a detailed description of the available parameters listed in Element .

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/indexing endpoint. If the POST request is successful, the response includes the key of the new ticketing policy. For example:

   {
     "key": "aa423b72-0d0f-4275-be30-494e9a99ffad",
     "meta": {
       "href": "/api/configuration/policies/indexing/aa423b72-0d0f-4275-be30-494e9a99ffad",
       "parent": "/api/configuration/policies/indexing",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Reporting

Topics:

Reporting

List of endpoints for configuring reporting, and accessing the generated reports.

URL

GET https://<IP-address-of-SPS>/api/configuration/reporting

Cookies

Sample request

The following command lists the available endpoints.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting

Response

The following is a sample response received when listing the available endpoints.

For details of the meta object, see Message format.

{
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/reporting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/ssh",
    "parent": "/api/configuration",
    "previous": "/api/configuration/rdp",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "content_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/content_subchapters"
      }
    },
    {
      "key": "custom_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/custom_subchapters"
      }
    },
    {
      "key": "predefined_reports",
      "meta": {
        "href": "/api/configuration/reporting/predefined_reports"
      }
    },
    {
      "key": "reports",
      "meta": {
        "href": "/api/configuration/reporting/reports"
      }
    },
    {
      "key": "statistics_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/statistics_subchapters"
      }
    }
  ]
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Reports

List of the configured reports.

URL

GET https://<IP-address-of-SPS>/api/configuration/reporting/reports

Cookies

Sample request

The following command lists the configured reports.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/reports

The following command retrieves the properties of a specific report.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/reports/<key_value>

Response

The following is a sample response received when listing reports.

For details of the meta object, see Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/reports",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/statistics_subchapters",
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/predefined_reports",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "7798770004e472c8576912",
      "meta": {
        "href": "/api/configuration/reporting/reports/7798770004e472c8576912"
      }
    },
    {
      "key": "8292675195707f19d932af",
      "meta": {
        "href": "/api/configuration/reporting/reports/8292675195707f19d932af"
      }
    }
  ]
}

When retrieving the endpoint of a specific report, the response is the following.

{
  "body": {
    "access": [
      "report"
    ],
    "chapters": [
      {
        "name": "System health",
        "subchapters": [
          {
            "name": "system_health_network_connections",
            "selection": "builtin"
          },
          {
            "name": "system_health_load_average",
            "selection": "builtin"
          }
        ]
      },
      {
        "name": "All connections",
        "subchapters": [
          {
            "name": "connection_each_scb_top10_channel_types_each",
            "selection": "builtin"
          },
          {
            "name": "connection_each_scb_top10_portforward_targets_each",
            "selection": "builtin"
          }
        ]
      },
      {
        "name": "Search statistics",
        "subchapters": [
          {
            "reference": "21111736175707f1df8bea1",
            "selection": "custom"
          }
        ]
      },
      {
        "name": "Misc",
        "subchapters": [
          {
            "reference": "13869311625707e0a3e0892",
            "selection": "custom"
          }
        ]
      },
      {
        "name": "Advanced statistics",
        "subchapters": [
          {
            "reference": "5983143445707eb740fee3",
            "selection": "custom"
          }
        ]
      }
    ],
    "email_recipients": {
      "recipients": [
        "admin@company.com"
      ],
      "selection": "other"
    },
    "frequency": {
      "day": false,
      "month": true,
      "week": false
    },
    "logo_id": "logoC890jH",
    "name": "all-options",
    "send_report_in_email": true
  },
  "key": "8292675195707f19d932af",
  "meta": {
    "first": "/api/configuration/reporting/reports/7798770004e472c8576912",
    "href": "/api/configuration/reporting/reports/8292675195707f19d932af",
    "last": "/api/configuration/reporting/reports/8292675195707f19d932af",
    "next": null,
    "parent": "/api/configuration/reporting/reports",
    "previous": "/api/configuration/reporting/reports/12046247915707e5d6a5c59",
    "transaction": "/api/transaction"
  }
}

Examples:

Set the e-mail recipients to the default (as configured in the reporting_address element of the /api/configuration/management/email endpoint):

"email_recipients": {
  "selection": "default"
}

Create a custom set of e-mail recipients:

"email_recipients": {
  "recipients": [
    "<email-1>",
    "<email-2>"
  ],
  "selection": "other"
}

Add a reporting chapter with built-in subchapters:

"chapters": [
  {
    "name": "<custom-name>",
    "subchapters": [
      {
        "name": "system_health_filesystem_usage",
        "selection": "builtin"
      },
      {
        "name": "system_health_network_connections",
        "selection": "builtin"
      },
      {
        "name": "system_health_load_average",
        "selection": "builtin"
      }
    ]
  }
        
Add a reporting chapter with custom, content, or statistics subchapters:
"chapters": [
  {
    "name": "<custom-name>",
    "subchapters": [
      {
        "reference": "<key-of-subchapter>",
        "selection": "custom"
      },
      {
        "reference": "<key-of-subchapter>",
        "selection": "custom"
      }
    ]
  }
    

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Add a report

To add a report, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new report.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/reports endpoint. You can find a detailed description of the available parameters listed in Element .

   If the POST request is successful, the response includes the key of the new report.

   {
     "key": "26ddf648-9a21-4a7f-af56-9cea575785a9",
     "meta": {
       "href": "/api/configuration/reporting/reports/26ddf648-9a21-4a7f-af56-9cea575785a9",
       "parent": "/api/configuration/reporting/reports",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify a report

To modify a report, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the report.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/reports/<key-of-the-report> endpoint. You can find a detailed description of the available parameters listed in Element .

3. Commit your changes.

   For details, see Commit a transaction.