IBM OpenPages REST API V2 for OpenPages as a Service

Introduction

Last updated: 2023-03-15

IBM® OpenPages® is an AI-driven, highly scalable governance, risk and compliance (GRC) solution. The IBM OpenPages® GRC REST API provides access to IBM OpenPages® data and metadata. This data-centric API is specified in terms of resources, their URIs, and actions that can be performed on these URIs.

Endpoint URIs

In the IBM OpenPages model, the metadata it defines, and their corresponding data can be accessed, updated, and created using the REST API. The REST API takes the form of URIs for these resources. The complete set of supported actions, their paths, parameters, and corresponding returned codes are defined. Data sent and returned during these HTTP interactions can either be in the HTTP body or as attachments.

The base URL for IBM OpenPages API endpoints come from your individual service instance. To find the URL, click the service instance in your Resource list and click Environment. Use the value that's listed in the Fixed URL field. For example:

https://21181e99-2f47-4ca8-8594-4b329353810c.us-east-1.aws.openpages.ibm.com

In IBM OpenPages as a Service, /opgrc/api is used as the root of every path. The specification of the URI address and the naming of path segments is not arbitrary. Every URI begins with {base_url}/opgrc/api.

Examples of URI paths for IBM OpenPages REST API V2 for OpenPages as a Service:

{base_url}/opgrc/api/v2/configuration/tags
{base_url}/opgrc/api/v2/configuration/currencies/{code}/exchange_rates
{base_url}/opgrc/api/v2/scim/Groups/{id}
{base_url}/opgrc/api/v2/workflows/definitions/version/{id}

Support for SCIM

The endpoints for Groups, ResourceTypes, Schema, ServiceProviderConfig, and Users are based on the SCIM 2.0 specification. Note that the SCIM ETags feature is not supported.

For more information about SCIM, see System for Cross-domain Identity Management: Protocol.

Authentication

To work with the API, you must use an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

You can generate an IAM token for an authenticated user or service ID by using the IAM Identity Services API. IAM tokens are generated by using the user or service ID's API key. For more information, see Generating an IBM Cloud IAM token by using an API key.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer {TOKEN}'.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with your IAM API key.

Security scheme

Authentication to this API's methods uses one of the following security schemes.

bearerToken

Attribute

Value

Type
HTTP
Scheme
Bearer
Bearer format
JWT

basicAuth

You can use the basic authentication security scheme for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. However, it is not available for OpenPages as a Service.

Attribute

Value

Type
HTTP
Scheme
Basic

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. For entire list of event types, see Auditing events for IBM OpenPages.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`500`	Internal Server Error	Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

/v2/folders/resources

The default page size is 100 objects. To use a different page size, use the limit query parameter.

For any request that uses pagination, the response may include following urls to make subsequent requests :

first: The URL for requesting the first page of results.
next: The URL for requesting the next page of results. The next property is omitted on the last page.
previous: The URL for requesting the previous page of results. The previous property is omitted on the first page.
last: The URL for requesting the last page of results. These URLs retain the same limit parameters that were used for the initial request.

Gets a list of tags. Set the only_enabled query parameter to true to request only enabled tags. If only_enabled is not set or if it is set to false, all tags are returned.

GET /v2/configuration/tags

Auditing

Calling this method generates the following auditing event.

openpages.tag.list

Request

Query Parameters

only_enabled
boolean
If set to true, returns only enabled tags. Default is false.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/tags"

Response Body

TagTypes

Defines Tag Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "tags": [
    {
      "tag_id": "1",
      "name": "Tag1da495b22f2d0",
      "description": "Tag1 description",
      "enabled": "true",
      "created_on": "2022-11-23T03:10:03.081-05:00",
      "created_by": "OpenPagesAdministrator",
      "modified_date": "2022-11-23T03:10:03.081-05:00",
      "last_modified_by": "OpenPagesAdministrator"
    },
    {
      "tag_id": "2",
      "name": "Tag2da495b22f2d0",
      "description": "Tag2 description",
      "enabled": "false",
      "created_on": "2022-11-23T03:10:03.128-05:00",
      "created_by": "OpenPagesAdministrator",
      "modified_date": "2022-11-23T03:10:03.425-05:00",
      "last_modified_by": "OpenPagesAdministrator"
    }
  ]
}

Adds Tags to the system.

POST /v2/configuration/tags

Auditing

Calling this method generates the following auditing event.

openpages.tag.create

Request

Request Body

Required*

TagTypes

Tag Types to create

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "tags": [ { "name": "PenTest", "description": "Tag for pen test" } ] }'   "{base_url}/v2/configuration/tags"

Response

Response Body

TagTypes

Defines Tag Types

Status Code

201
Tags Created
400
Tag name cannot be null.

Example responses

Status 201: Tags Created

201

{
  "tags": [
    {
      "tag_id": "1",
      "name": "Tag1da495b22f2d0",
      "description": "Tag1 description",
      "enabled": "true",
      "created_on": "2022-11-23T03:10:03.081-05:00",
      "created_by": "OpenPagesAdministrator",
      "modified_date": "2022-11-23T03:10:03.081-05:00",
      "last_modified_by": "OpenPagesAdministrator"
    },
    {
      "tag_id": "2",
      "name": "Tag2da495b22f2d0",
      "description": "Tag2 description",
      "enabled": "false",
      "created_on": "2022-11-23T03:10:03.128-05:00",
      "created_by": "OpenPagesAdministrator",
      "modified_date": "2022-11-23T03:10:03.425-05:00",
      "last_modified_by": "OpenPagesAdministrator"
    }
  ]
}

Status 400: Tag name cannot be null.

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-2",
      "message": "Bad Request - Tag name cannot be null or empty."
    }
  ]
}

Decrypts all data, such as OpenPages storage and sensitive information in OpenPages database, using an external key.

PUT /v2/configuration/decrypt_with_external_key

Auditing

Calling this method generates the following auditing event.

openpages.configuration-encryption.set-off

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/decrypt_with_external_key"

Response

Response Body

SimpleRestResponseType

Defines a REST response having primitives

Status Code

200
200

Example responses

200
{}

Encrypts all data, such as OpenPages storage and sensitive information in OpenPages database, using an external key.

PUT /v2/configuration/encrypt_with_external_key

Auditing

Calling this method generates the following auditing event.

openpages.configuration-encryption.set-on

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/encrypt_with_external_key"

Response

Response Body

SimpleRestResponseType

Defines a REST response having primitives

Status Code

200
200

Example responses

200
{ "texts": [ {} ] }

Gets the Base Currency information for this system. The Base Currency is typically set at install time.

GET /v2/configuration/currencies/base

Auditing

Calling this method generates the following auditing event.

openpages.base-currency.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/currencies/base"

Response

Response Body

CurrencyType

Defines Currency Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "iso_code": "USD",
  "name": "United States of America, Dollars",
  "symbol": "$",
  "precision": 2,
  "is_base_currency": true,
  "is_enabled": true,
  "id": "10"
}

Gets values for all child configurations in the specified path.

GET /v2/configuration/settings/all/{setting_path}

Auditing

Calling this method generates the following auditing event.

openpages.setting.list

Request

Path Parameters

setting_path
Required*
string
Get the child settings for the specified path. For example, /OpenPages/Platform/CP4D/Sync/Profiles. Because the path contains slashes (/), it must be URL-encoded.

Possible values: 1 ≤ length ≤ 2048, Value must match regular expression [A-Za-z0-9 /_.-]*
Example: /OpenPages/Platform/CP4D/Sync/Profiles

Query Parameters

offset
int32
0-based index of the first query result.

Default: 0
limit
int32
Specifies the desired maximum number of results per page.

Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/settings/all/{setting_path}"

Response

Response Body

SettingTypes

Collection of Setting Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "settings": [
    {
      "key": "/OpenPages/Applications/Assistant/Embed Options",
      "value": ""
    },
    {
      "key": "/OpenPages/Applications/Assistant/Integration ID",
      "value": ""
    },
    {
      "key": "/OpenPages/Applications/Assistant/Assistant URL",
      "value": ""
    }
  ]
}

Gets a list of currencies. Set the only_enabled query parameter to true to request only enabled currencies. If only_enabled is not set or if it is set to false, all currencies are returned.

GET /v2/configuration/currencies

Auditing

Calling this method generates the following auditing event.

openpages.currency.list

Request

Query Parameters

only_enabled
boolean
If set to true, returns only enabled currencies. Default is false.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/currencies"

Response

Response Body

CurrencyTypes

Defines collection of Currency Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "currencies": [
    {
      "iso_code": "USD",
      "name": "United States of America, Dollars",
      "symbol": "$",
      "precision": 2,
      "is_base_currency": true,
      "is_enabled": true,
      "id": "10"
    },
    {
      "iso_code": "CAD",
      "name": "Canadian Dollar",
      "symbol": "$",
      "precision": 2,
      "is_base_currency": false,
      "is_enabled": true,
      "id": "350"
    }
  ]
}

Gets the details about a Currency by specifying an ISO code.

GET /v2/configuration/currencies/{code}

Auditing

Calling this method generates the following auditing event.

openpages.currency.get

Request

Path Parameters

code
Required*
string
ISO currency code.

Possible values: 1 ≤ length ≤ 6, Value must match regular expression [A-Z]*
Example: USD

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/currencies/{code}"

Response

Response Body

CurrencyType

Defines Currency Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "iso_code": "USD",
  "name": "United States of America, Dollars",
  "symbol": "$",
  "precision": 2,
  "is_base_currency": true,
  "is_enabled": true,
  "id": "10"
}

Sets the status of a Currency to be enabled or disabled.

PUT /v2/configuration/currencies/{code}

Auditing

Calling this method generates the following auditing event.

openpages.currency.update

Request

Path Parameters

code
Required*
string
ISO currency code.

Possible values: 1 ≤ length ≤ 6, Value must match regular expression [A-Z]*
Example: USD

Query Parameters

enable
Required*
boolean
Status to set on the Currency.

Example: true

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/configuration/currencies/{code}?enable=true"

Response

Status Code

202
Set Currency status successfully.

No Sample Response

This method does not specify any sample responses.

Gets the Current Reporting Period information. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

GET /v2/configuration/reporting_periods/current

Auditing

Calling this method generates the following auditing event.

openpages.current-reporting-period.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/reporting_periods/current"

Response

Response Body

ReportingPeriodType

Defines Reporting Period Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "10",
  "label": "Current Reporting Period",
  "description": "Current Reporting Period",
  "finalizedDate": "2022-09-09T21:58:11.678-04:00",
  "creationDate": "2022-09-09T21:58:11.000-04:00",
  "modifiedDate": "2022-09-09T21:58:11.678-04:00"
}

Gets exchange rates for a Currency by specifying an ISO currency code. The default response returns the current exchange rate. To get the exchange rate for a particular date, use the date parameter.

GET /v2/configuration/currencies/{code}/exchange_rates

Auditing

Calling this method generates the following auditing event.

openpages.currency-history.list

Request

Path Parameters

code
Required*
string
ISO currency code.

Possible values: 1 ≤ length ≤ 6, Value must match regular expression [A-Z]*
Example: USD

Query Parameters

date
string
The date for which to retrieve the exchange rate. The expected date format is ISO 8601 'yyyyMMdd'T'HHmmss'Z''

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400
history
boolean
Return all the historical exchange rates for the Currency if the date is not specified.
offset
int32
0-based index of the first query result.

Default: 0
limit
int32
Specifies the desired maximum number of results per page.

Possible values: value ≤ 1000
Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/currencies/{code}/exchange_rates?date=20220616T075200-0400"

Response

Response Body

ExchangeRateTypes

Defines collection of Exchange Rate Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "total_count": 1,
  "offset": 0,
  "limit": 100,
  "exchange_rates": [
    {
      "id": "1",
      "currency_code": "USD",
      "rate": 1,
      "start_date": "2022-01-01T00:00:00.000-05:00"
    }
  ]
}

Sets an exchange rate for a Currency.

POST /v2/configuration/currencies/{code}/exchange_rates

Auditing

Calling this method generates the following auditing event.

openpages.currency.update

Request

Path Parameters

code
Required*
string
ISO currency code.

Possible values: 1 ≤ length ≤ 6, Value must match regular expression [A-Z]*
Example: USD

Request Body

Required*

ExchangeRateType

Exchange rate to set.

Examples:

Set exchange rate

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "rate": 0.8636, "start_date": "2015-05-20T00:00:00.000-05:00" }'   "{base_url}/v2/configuration/currencies/{code}/exchange_rates"

Response

Status Code

204
Exchange rate set successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Gets the Localized Application Text label for the current user's locale.

GET /v2/configuration/text/{text_key}

Auditing

Calling this method generates the following auditing event.

openpages.application-text.get

Request

Path Parameters

text_key
Required*
string
The application text key. For example, "com.label.activityview.detailview".

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 _.-]*
Example: com.label.activityview.detailview

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/text/{text_key}"

Response

Response Body

SimpleRestResponseType

Defines a REST response having primitives

Status Code

200
200

Example responses

200
{ "response": "Detail View" }

Gets all Localized Application Text labels for the current user's locale. Use the categoryFilters parameter to filter application texts by category names. Use the includeLocalizedLabels parameter to include localized labels for all locales.

GET /v2/configuration/text

Auditing

Calling this method generates the following auditing event.

openpages.application-text.list

Request

Query Parameters

include_localized_labels
boolean
Include localized labels for all locales.

Default: false
category_filters
string
Comma-separated category name to filter application texts.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
offset
int32
0-based index of the first query result.

Default: 0
limit
int32
Specifies the desired maximum number of results per page.

Possible values: value ≤ 1000
Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/text"

Response

Response Body

ApplicationTextTypes

Defines application texts

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "text": [
    {
      "name": "com.image.alt.File",
      "category": "Miscellaneous",
      "localized_label": "File"
    },
    {
      "name": "instruction.busentity.move.select",
      "category": "Miscellaneous",
      "localized_label": "Select the target {0}:"
    }
  ]
}

Gets a Profile summary.

GET /v2/configuration/profiles/{profile}

Auditing

Calling this method generates the following auditing event.

openpages.profile.get

Request

Path Parameters

profile
Required*
string
Profile name or ID.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 _-]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/profiles/{profile}"

Response

Response Body

ProfileType

Defines a Profile Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1",
  "name": "Default",
  "description": "Default Profile",
  "is_default": false,
  "is_fallback": false,
  "is_enabled": true,
  "is_deleted": false
}

Gets a full profile definition including object types, fields, and views.

GET /v2/configuration/profiles/{profile}/definition

Auditing

Calling this method generates the following auditing event.

openpages.profile.get

Request

Path Parameters

profile
Required*
string
Profile name or ID.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 _-]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/profiles/{profile}/definition"

Response

Response Body

ProfileType

Defines a Profile Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "Default",
  "id": "1",
  "description": "Default Profile",
  "isDefault": false,
  "isFallback": false,
  "isDisabled": false,
  "isDeleted": false,
  "objectTypes": {
    "objectType": []
  },
  "resourceAssociations": {
    "resourceAssociation": [
      {
        "resourceType": "DEFAULT_HOME_PAGE_TAB",
        "tabEnabled": true,
        "tabOrder": 1,
        "homePagePanelsConfiguration": ""
      }
    ]
  }
}

Gets the definitions of Fields associated with the specified Profile for the specified Object Type. For example, Fields from the SOXBusEntity in the OpenPages Modules Master Profile.

GET /v2/configuration/profiles/fields

Auditing

Calling this method generates the following auditing event.

openpages.profile-object-field.list

Request

Query Parameters

profile
Required*
string
Profile name

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 _-]*
type
Required*
string
Object Type system name

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9]*
Example: SOXBusEntity

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/profiles/fields?profile={profile}&type=SOXBusEntity"

Response

Response Body

ProfileFieldDefinitionTypes

Collection of Profile field definition Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "fields": [
    {
      "id": "9104",
      "name": "Name",
      "group_name": "System Fields",
      "localized_label": "Name",
      "data_type": "STRING_TYPE",
      "required": true,
      "display_type": "Text"
    },
    {
      "id": "9105",
      "name": "Description",
      "group_name": "System Fields",
      "localized_label": "Description",
      "data_type": "STRING_TYPE",
      "required": false,
      "display_type": "Text Area"
    }
  ]
}

Gets a list of all Profiles summary information.

GET /v2/configuration/profiles

Auditing

Calling this method generates the following auditing event.

openpages.profile.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/profiles"

Response

Response Body

ProfileTypes

Collection of Profile Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "profiles": [
    {
      "id": "4",
      "name": "BCM End User",
      "description": "Generated by 8.3",
      "isDefault": false,
      "isFallback": false,
      "isEnabled": true,
      "isDeleted": false
    },
    {
      "id": "1",
      "name": "Default",
      "description": "Default Profile",
      "isDefault": false,
      "isFallback": false,
      "isEnabled": true,
      "isDeleted": false
    }
  ]
}

Gets a specific Reporting Period by name. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

GET /v2/configuration/reporting_periods/{reporting_period}

Auditing

Calling this method generates the following auditing event.

openpages.reporting-period.get

Request

Path Parameters

reporting_period
Required*
string
The name of the Reporting Period.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 ]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/reporting_periods/{reporting_period}"

Response

Response Body

ReportingPeriodType

Defines Reporting Period Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "10",
  "label": "Current Reporting Period",
  "description": "Current Reporting Period",
  "finalizedDate": "2022-09-09T21:58:11.678-04:00",
  "creationDate": "2022-09-09T21:58:11.000-04:00",
  "modifiedDate": "2022-09-09T21:58:11.678-04:00"
}

Gets a list of all Reporting Periods. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

GET /v2/configuration/reporting_periods

Auditing

Calling this method generates the following auditing event.

openpages.reporting-period.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/reporting_periods"

Response

Response Body

ReportingPeriodTypes

Collection of ReportingPeriod Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "reporting_periods": [
    {
      "id": "-1",
      "label": "Current Reporting Period",
      "description": "Current Reporting Period",
      "finalizedDate": "2022-09-09T21:58:11.678-04:00",
      "creationDate": "2022-09-09T21:58:11.000-04:00",
      "modifiedDate": "2022-09-09T21:58:11.678-04:00"
    }
  ]
}

Gets the value of the configuration setting by the specified path.

GET /v2/configuration/settings/{setting_path}

Auditing

Calling this method generates the following auditing event.

openpages.setting.get

Request

Path Parameters

setting_path
Required*
string
The setting path. For example, /OpenPages/Applications/GRCM/Audit Trail/Show Audit Trail For Custom Forms. Because the path contains slashes (/), it must be URL-encoded.

Possible values: 1 ≤ length ≤ 2048, Value must match regular expression [A-Za-z0-9 /_.-]*
Example: /OpenPages/Applications/GRCM/Audit Trail/Show Audit Trail For Custom Forms

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/settings/{setting_path}"

Response

Response Body

SettingType

Defines a Setting Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "key": "/OpenPages/Applications/GRCM/Audit Trail/Show Audit Trail For Custom Forms",
  "value": "false"
}

Gets the status of System Admin Mode. The status can be either true, meaning that System Admin Mode is enabled, or false.

GET /v2/configuration/admin_mode

Auditing

Calling this method generates the following auditing event.

openpages.system-admin-mode.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/admin_mode"

Response

Response Body

SimpleRestResponseType

Defines a REST response having primitives

Status Code

200
200

Example responses

200
{ "response": "true" }

Sets the status of System Admin Mode. The status can be either true, meaning that System Admin Mode is enabled, or false. This operation requires System Administration Mode permission.

PUT /v2/configuration/admin_mode

Auditing

Calling this method generates the following auditing event.

openpages.system-admin-mode.update

Request

Query Parameters

enable
Required*
boolean
Set true to enable System Admin Mode , or false to disable.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/configuration/admin_mode?enable=true"

Response

Status Code

202
Set System Admin Mode successfully.

No Sample Response

This method does not specify any sample responses.

Gets the details about the tag identified by the specified tag_id.

GET /v2/configuration/tags/{tagid}

Auditing

Calling this method generates the following auditing event.

openpages.tag.get

Request

Path Parameters

tagid
Required*
string
Tag ID.

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/configuration/tags/{tagid}"

Response

Response Body

tag_type

Defines Tag Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "tag_id": "1",
  "name": "Tag1da495b22f2d0",
  "description": "Tag1 description",
  "enabled": "true",
  "created_on": "2022-11-23T03:10:03.081-05:00",
  "created_by": "user001",
  "modified_date": "2022-11-23T03:10:03.081-05:00",
  "last_modified_by": "user001"
}

Updates an existing Tag.

PUT /v2/configuration/tags/{tagid}

Auditing

Calling this method generates the following auditing event.

openpages.tag.update

Request

Path Parameters

tagid
Required*
string
Tag ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Request Body

Required*

tag_type

Tag Type to update

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{}'   "{base_url}/v2/configuration/tags/{tagid}"

Response

Response Body

tag_type

Defines Tag Type

Status Code

200
Tag updated

Example responses

Status 200: 200 ok Summary

200

{
  "tag_id": "1",
  "name": "EntityTag",
  "description": "Tag to mark entity",
  "enabled": "true",
  "created_on": "2022-11-23T03:10:03.081-05:00",
  "created_by": "user001",
  "modified_date": "2022-11-23T03:15:03.081-05:00",
  "last_modified_by": "user001"
}

Integrates the Cognos Service into OpenPages. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

PUT /v2/configuration/integrate_cognos_service

Auditing

Calling this method generates the following auditing event.

openpages.cognos.configure

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/configuration/integrate_cognos_service"

Response

Status Code

202
Integration with Cognos successful.

No Sample Response

This method does not specify any sample responses.

Sets Currency exchange rates with a list of exchange rates for multiple currencies.

POST /v2/configuration/currencies/exchange_rates

Auditing

Calling this method generates the following auditing event.

openpages.currency-list.update

Request

Request Body

Required*

ExchangeRateTypes

List of exchange rates to set for multiple currencies

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "exchange_rates": [ { "currency_code": "CAD", "rate": 0.8637 }, { "currency_code": "EUR", "rate": 1.1143, "start_date": "2015-05-21T00:00:00.000-05:00" } ] }'   "{base_url}/v2/configuration/currencies/exchange_rates"

Response

Status Code

204
Set multiple exchange rates successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Enables or disables Trace Log options.

PUT /v2/configuration/traces

Auditing

Calling this method generates the following auditing event.

openpages.trace-options.update

Request

Request Body

Required*

TraceLogListType

Trace Log options to set

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "trace_list": [] }'   "{base_url}/v2/configuration/traces"

Response

Status Code

202
Trace Log options were enabled or disabled successfully.

No Sample Response

This method does not specify any sample responses.

Adds child associations from one GRC Object to other GRC Objects.

POST /v2/contents/{id}/associations/children

Auditing

Calling this method generates the following auditing event.

openpages.resource.add

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

AssociationNodeTypes

List of child associations to create

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "associations": [ { "id": "8196", "type": "child" } ] }'   "{base_url}/v2/contents/{id}/associations/children"

Response

Status Code

202
Accepted request to create child associations
400
Association ID cannot be null.

Example responses

Status 400: Association ID cannot be null.

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "400",
      "message": "Bad Request - association id cannot be null."
    }
  ]
}

Removes child associations from one GRC Object to other GRC Objects.

DELETE /v2/contents/{id}/associations/children

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.delete

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

children
string
Comma-delimited list of child IDs

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/contents/{id}/associations/children"

Response

Status Code

204
Object child associations deleted successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Adds parent associations from one GRC Object to other GRC Objects.

POST /v2/contents/{id}/associations/parents

Auditing

Calling this method generates the following auditing event.

openpages.resource.add

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

AssociationNodeTypes

List of parent associations to create

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "associations": [ { "id": "8174", "type": "parent" } ] }'   "{base_url}/v2/contents/{id}/associations/parents"

Response

Status Code

202
Accepted request to create parent associations
400
Association ID cannot be null.

Example responses

Status 400: Association id cannot be null.

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "400",
      "message": "Bad Request - association id cannot be null."
    }
  ]
}

Removes parent associations from one GRC Object to other GRC Objects.

DELETE /v2/contents/{id}/associations/parents

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.delete

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

parents
string
Comma-delimited list of parent IDs

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/contents/{id}/associations/parents"

Response

Status Code

204
Object parent associations deleted successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Gets a list of all Tags associated with the GRC Object.

GET /v2/contents/{id}/tags

Auditing

Calling this method generates the following auditing event.

openpages.tag-association.list

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path. For example,
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/tags"

Response

Response Body

TagTypes

Defines Tag Types

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "tags": [
    {
      "tag_id": "1",
      "name": "HighRisk",
      "description": "HighRisk",
      "enabled": "true",
      "created_on": "2022-06-22T10:18:08.350-0400",
      "created_by": "OpenPagesAdministrator",
      "modified_date": "2022-06-22T10:18:08.350-0400",
      "last_modified_by": "OpenPagesAdministrator"
    }
  ]
}

Associates one or more Tags to a Object. In each TagType in the request, set the tagID attribute to be the target of the association.

POST /v2/contents/{id}/tags

Auditing

Calling this method generates the following auditing event.

openpages.tag-association.add

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

TagTypes

List of Tags to associate

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "tags": [ { "tag_id": "1" } ] }'   "{base_url}/v2/contents/{id}/tags"

Response

Status Code

204
Tags associated successfully. No Content.
400
Tag ID cannot be null.

Example responses

Status 400: Tag ID cannot be null.

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-2",
      "message": "Bad Request - Tag id cannot be null."
    }
  ]
}

Disassociates one or more Tags from a GRC Object.

DELETE /v2/contents/{id}/tags

Auditing

Calling this method generates the following auditing event.

openpages.tag-association.delete

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

tag_ids
string
Comma-delimited list of Tag IDs

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*
Example: 21,22

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/contents/{id}/tags?tag_ids=21,22"

Response

Status Code

204
Tags disassociated successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Gets the child object types the current user can create for the parent object specified by the ID. This list returns only the object types specified by the types parameter. The object types a user can create are determined by the current security assigned to the user and any security rules that apply globally. Users can get their own permissions only.

GET /v2/contents/permissions/allowedtocreatetypes

Auditing

Calling this method generates the following auditing event.

openpages.resource-permission.get

Request

Query Parameters

user
string
User name or ID to check permissions for. If this value is null, the operation checks the permissions for the current user. Only Super Administrators or Security Administrators can specify a value for this parameter. Users without permission that specify a value receive a response of Not Authorized.

Possible values: 1 ≤ length ≤ 320, Value must match regular expression [A-Za-z0-9]*
types
string
The list of GRC Object Types to check. Specify a comma-separated list of type names or IDs. If this value is null, the operation returns a list of all types in the system.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
Example: SOXTask,Waiver

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/permissions/allowedtocreatetypes?types=SOXTask,Waiver"

Response

Response Body

AllowedToCreateType

Defines a REST response having list of allowed Object types to create

Status Code

200
200 OK

Example responses

200
{ "allowedtocreatetypes": [ "SOXTask", "Waiver" ] }

Gets the child object types that the current user can create for the parent object specified by the ID. This list returns only the object types specified by the types parameter. The object types a user can create are determined by the current security assigned to the user and any security rules that apply globally. Users can get only their own permissions.

GET /v2/contents/{id}/permissions/allowedtocreatetypes

Auditing

Calling this method generates the following auditing event.

openpages.resource-permission.get

Request

Path Parameters

id
Required*
string
GRC Object ID or path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

types
string
The list of Object Types to check. Specify a comma-separated list of type names or IDs. If this value is null, the operation returns a list of all types in the system.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
Example: SOXTask,Waiver

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/permissions/allowedtocreatetypes?types=SOXTask,Waiver"

Response

Response Body

AllowedToCreateType

Defines a REST response having list of allowed Object types to create

Status Code

200
200 OK

Example responses

200
{ "allowedtocreatetypes": [ "SOXTask", "Waiver" ] }

Gets a list of all GRC Object associations to other GRC Objects.

GET /v2/contents/{id}/associations

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.list

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path. Examples:
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

association_type
string
Filters object associations based on association type. Value can be parent or child.

Allowable values: [parent,child]
offset
int32
0-based index of the first query result.

Default: 0
limit
int32
Specifies the desired maximum number of results per page.

Possible values: value ≤ 1000
Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/associations"

Response

Response Body

AssociationNodeTypes

Defines Association Node Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "associations": [
    {
      "id": "7821",
      "type_definition_id": "5",
      "path": "/_op_sox/Project/Default/BusinessEntity/Global Financial Services/Asia Pac/Agency Services/Agency Services.txt",
      "association_definition_id": "4",
      "type": "parent"
    },
    {
      "id": "13501",
      "type_definition_id": "7",
      "path": "/_op_sox/Project/Default/IssueActionItems/Test 01/issue7_ISSUE_ACTION_ITEM_000001.txt",
      "association_definition_id": "8",
      "type": "child"
    }
  ]
}

Adds either parent or child associations from one GRC Object to other GRC Objects. In each AssociationNodeType in the request, set the id attribute to be the object to make associations with.

POST /v2/contents/{id}/associations

Auditing

Calling this method generates the following auditing event.

openpages.resource.add

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

AssociationNodeTypes

Request body that includes the list of associations to create

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "associations": [ { "id": "6045", "type": "parent" } ] }'   "{base_url}/v2/contents/{id}/associations"

Response

Status Code

204
1. No Content.
400
Association ID cannot be null.

Example responses

Status 400: Association ID cannot be null.

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-2",
      "message": "Bad Request - Association ID cannot be null."
    }
  ]
}

Removes the associations from one GRC Object to other GRC Objects.

DELETE /v2/contents/{id}/associations

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.delete

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

parents
string
Comma-delimited list of parent IDs

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*
children
string
Comma-delimited list of child IDs

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/contents/{id}/associations"

Response

Status Code

204
Object associations deleted successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Copies a list of GRC Objects to a parent object specified by the id parameter. The copied Objects are created as children of the specified parent. The response contains a list of the copies that were made.

PUT /v2/contents/{id}/action/copy

Auditing

Calling this method generates the following auditing event.

openpages.resource-copy.commit

Request

Path Parameters

id
Required*
string
Parent GRC Object ID or Path to copy the other objects to.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

ActionType

Request body containing the list of Object IDs to be copied and options for the copy action.

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "ids": [ "19001" ], "options": { "include_children": true, "conflict_behavior": "createcopyof", "type_definitions": [ "SOXIssue" ], "type_associations": [ { "parent_object_type": "SOXProcess", "child_object_type": "SOXIssue" } ], "auto_name_children": false } }'   "{base_url}/v2/contents/{id}/action/copy"

Response

Response Body

GrcObjectTypes

Collection of GrcObjects

Status Code

200
200

Example responses

Status 200: Copied list of GRC Objects

200

{
  "grcobjects": [
    {
      "fields": [
        {
          "value": "19002",
          "id": "28",
          "data_type": "ID_TYPE",
          "name": "Resource ID",
          "has_changed": false
        },
        {
          "value": "newaction",
          "id": "56",
          "data_type": "STRING_TYPE",
          "name": "Description",
          "has_changed": false
        },
        {
          "date": "2022-06-26T02:31:32.000-0400",
          "id": "60",
          "data_type": "DATE_TYPE",
          "name": "Last Modification Date",
          "has_changed": false
        }
      ],
      "type_definition_id": "7",
      "is_checkout": false,
      "is_locked": false,
      "primary_parent_id": "12502",
      "name": "issue7_ISSUE_ACTION_ITEM_000022",
      "id": "19002",
      "path": "/_op_sox/Project/Default/IssueActionItems/issue7_ISSUE_ACTION_ITEM_000022.txt",
      "description": "New action",
      "creator": "user001",
      "creation_date": "2022-06-26T02:31:32.000-0400",
      "modified_date": "2022-06-26T02:31:32.000-0400",
      "parent_folder_id": "18",
      "last_modified_by": "user001"
    }
  ]
}

Creates a new GRC Object instance. Can also create Document types with attachment content. The IDs used for type definitions and file types are available in the /types API.

type_definition_id could be either an Object Type's ID, such as 123, or its system name, such as SOXIssue. Object Type labels are not supported.
primary_parent_id can be either another Object Type's ID, such as 10101, or its full path, such as /_op_sox/Project/Default/Issue/Parent-Issue.txt.
Every field in the fields must be identified uniquely by the field's ID attribute, or an id such as "id": "456", or a name attribute such as "name": "OPSS-Iss:Status".

To create a Document object, set the attachment contents in the content_definition.children attribute of the payload. For binary file formats, set Base64-encoded file contents in the same attribute.

POST /v2/contents

Auditing

Calling this method generates the following auditing event.

openpages.resource.create

Request

Request Body

Required*

DocumentCreateType

Creates a GRC object.

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "fields": [ { "id": "141", "name": "OPLC-Std:LCComment", "value": "Object comment" }, { "name": "OPLC-Std:LCReadOnly", "value": "true" }, { "name": "OPSS-Iss:Identified By Group", "value": [ { "name": "Internal Audit" }, { "id": "3484" } ] }, { "name": "OPSS-Iss:Status", "value": { "name": "Open" } } ], "type_definition_id": "6", "name": "TestObjectCreate", "description": "Test GRC Object create V2" }'   "{base_url}/v2/contents"

Response

Response Body

GrcObjectType

GrcObject Type

Status Code

201
Object Created

Example responses

Status 201: GRC Object created

201

{
  "name": "TestObjectCreate",
  "id": "13056",
  "path": "/_op_sox/Project/Default/Issue/TestObjectCreate.txt",
  "creation_date": "2023-04-20T01:17:26.000-04:00",
  "modified_date": "2023-04-20T01:17:26.000-04:00",
  "description": "Test GRC Object create V2",
  "parent_folder_id": "17",
  "creator": "OpenPagesAdministrator",
  "last_modified_by": "OPSystem",
  "fields": [
    {
      "id": "28",
      "data_type": "ID_TYPE",
      "name": "Resource ID",
      "has_changed": false,
      "value": "13056"
    },
    {
      "id": "61",
      "data_type": "DATE_TYPE",
      "name": "Creation Date",
      "has_changed": false,
      "value": "2023-04-20T01:17:26.000-04:00"
    },
    {
      "id": "60",
      "data_type": "STRING_TYPE",
      "name": "Location",
      "has_changed": false,
      "value": "/_op_sox/Project/Default/Issue/TestObjectCreate.txt"
    },
    {
      "id": "3202",
      "data_type": "MULTI_VALUE_ENUM",
      "name": "OPSS-Issue:Domain",
      "has_changed": false,
      "values": [
        {
          "id": "8199",
          "name": "Compliance",
          "localized_label": "Compliance",
          "index": 1,
          "hidden": false
        }
      ]
    },
    {
      "id": "3207",
      "data_type": "ENUM_TYPE",
      "name": "OPSS-Issue:Status",
      "has_changed": false,
      "value": {
        "id": "8183",
        "name": "Open",
        "localized_label": "Open",
        "index": 2,
        "hidden": false
      }
    }
  ],
  "type_definition_id": "6",
  "is_checkout": false,
  "is_locked": false
}

Gets a GRC Object instance by ID or a relative path. Use optional parameters to control data returned.

GET /v2/contents/{id}

Auditing

Calling this method generates the following auditing event.

openpages.resource.get

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path. Examples:
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

field_filters
string
The list of fields to include in response. Comma-delimited list of system names of fields for the Object Type. Default response includes all fields.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
include_associations
string
Associations to other GRC Objects. Defaults to none for optimal performance.

Allowable values: [none,both,parent,child]
Default: none
include_workflow
string
Include associated workflow information.

Possible values: 1 ≤ length ≤ 5, Value must match regular expression [A-Za-z]*
Default: false
associationtype_filters
string
If including Associations, specify the list of Object Types to include.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]*
reporting_period_label
string
The Reporting Period name to retrieve the GRC Object from a particular period. Default is from the Current Period.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 :;#-+_%]*
Default: Current Reporting Period
evaluate_computed_fields
string
Computed fields are not evaluated by default. To include evaluated calculations in the response, set to true.

Possible values: 1 ≤ length ≤ 5, Value must match regular expression [A-Za-z]*
Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}"

Response

Response Body

GrcObjectType

GrcObject Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "fields": [
    {
      "value": "11502",
      "id": "28",
      "data_type": "ID_TYPE",
      "name": "Resource ID",
      "has_changed": false
    },
    {
      "id": "62",
      "data_type": "STRING_TYPE",
      "name": "Comment",
      "has_changed": false
    }
  ],
  "type_definition_id": "6",
  "is_checkout": false,
  "is_locked": false,
  "primary_parent_id": "6524",
  "name": "issue2",
  "id": "11502",
  "path": "/_op_sox/Project/Default/Issue/Test 01/issue2.txt",
  "description": "Issue created by user001",
  "creator": "user001",
  "creation_date": "2022-06-09T07:19:04.000-0400",
  "modified_date": "2022-06-10T06:49:28.000-0400",
  "parent_folder_id": "5444",
  "last_modified_by": "user001"
}

Updates an existing GRC Object instance or document. For larger document attachments, use the PUT /v2/contents/{id}/document endpoint.

type_definition_id could be either an Object Type's ID, such as 123, or its system name, such as SOXIssue. Object Type labels are not supported.
primary_parent_id could be either another Object Type's ID, such as 10101, or its full path, such as /_op_sox/Project/Default/Issue/Parent-Issue.txt.
Every Field in the fields must be identified uniquely by either the field's id attribute, or an id, such as "id": "456", or a name attribute, such as "name": "OPSS-Iss:Status".
When updating a Object and setting field types "MEDIUM_STRING_TYPE" and "LARGE_STRING_TYPE" values to null, the values for those fields are an empty String "" instead of NULL.

PUT /v2/contents/{id}

Auditing

Calling this method generates the following auditing event.

openpages.resource.update

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path. Examples:
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

DocumentCreateType

Update GRC object

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "fields": [ { "name": "OPSS-Iss:Identified By Group", "value": [ { "name": "Compliance Management" } ] } ], "type_definition_id": "6", "name": "TestObjectCreate", "description": "New Description GRC Object via Update V2" }'   "{base_url}/v2/contents/{id}"

Response

Response Body

GrcObjectType

GrcObject Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "TestObjectCreate",
  "id": "13056",
  "path": "/_op_sox/Project/Default/Issue/TestObjectCreate.txt",
  "creation_date": "2023-04-20T01:17:26.000-04:00",
  "modified_date": "2023-04-20T01:17:26.000-04:00",
  "description": "Test GRC Object create V2",
  "parent_folder_id": "17",
  "creator": "OpenPagesAdministrator",
  "last_modified_by": "OPSystem",
  "fields": [
    {
      "id": "28",
      "data_type": "ID_TYPE",
      "name": "Resource ID",
      "has_changed": false,
      "value": "13056"
    },
    {
      "id": "61",
      "data_type": "DATE_TYPE",
      "name": "Creation Date",
      "has_changed": false,
      "value": "2023-04-20T01:17:26.000-04:00"
    },
    {
      "id": "60",
      "data_type": "STRING_TYPE",
      "name": "Location",
      "has_changed": false,
      "value": "/_op_sox/Project/Default/Issue/TestObjectCreate.txt"
    },
    {
      "id": "3202",
      "data_type": "MULTI_VALUE_ENUM",
      "name": "OPSS-Issue:Domain",
      "has_changed": false,
      "values": [
        {
          "id": "8199",
          "name": "Compliance",
          "localized_label": "Compliance",
          "index": 1,
          "hidden": false
        }
      ]
    },
    {
      "id": "3207",
      "data_type": "ENUM_TYPE",
      "name": "OPSS-Issue:Status",
      "has_changed": false,
      "value": {
        "id": "8183",
        "name": "Open",
        "localized_label": "Open",
        "index": 2,
        "hidden": false
      }
    }
  ],
  "type_definition_id": "6",
  "is_checkout": false,
  "is_locked": false
}

Performs a "soft delete" on a GRC Object instance by ID. Information can be retrieved using the Find Deleted Resources endpoint.

DELETE /v2/contents/{id}

Auditing

Calling this method generates the following auditing event.

openpages.resource.delete

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/contents/{id}"

Response

Status Code

204
GRC Object deleted successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Finds deleted resources using filters. Can use paging for results. This operation can only be performed by a Super Administrator user. The results from this method can be used in the Purge Resource method.

GET /v2/contents/deletedresources

Auditing

Calling this method generates the following auditing event.

openpages.resource.list

Request

Query Parameters

filter
string
A filter to limit deleted resource results. For example, filter=Description like 'name'.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9 _@./#&+-]*
Example: Description like 'name'
start_row
int32
Paging start row index

Default: 0
end_row
int32
Paging end row index

Default: 0

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/deletedresources?filter=Description like 'name'"

Response

Response Body

DeletedResourceTypes

Collection of Deleted ResourceType Objects

Status Code

200
200 OK

Example responses

Status 200: List of Deleted Resources

200

{
  "deleted_resources": [
    {
      "id": "19002",
      "path": "/_op_sox/Project/Default/IssueActionItems/issue7_ISSUE_ACTION_ITEM_000022.txt",
      "is_folder": false,
      "creation_date": "2022-06-26T02:31:32.000-0400",
      "modified_date": "2022-06-26T03:06:51.000-0400",
      "description": "newaction",
      "creator": "6",
      "last_modified_by": "6",
      "type_definition_id": "7"
    }
  ]
}

Determines whether a user is allowed to create a new child Object of the specified parent GRC Object based on Role-based Security and Security Rules.

GET /v2/contents/{id}/permissions/cancreate/{type}

Auditing

Calling this method generates the following auditing event.

openpages.resource-permission.get

Request

Path Parameters

id
Required*
string
GRC Object ID or Path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*
type
Required*
string
The child Object Type.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]*

Query Parameters

folder
string
The folder ID to use when checking permissions. If null, use the default folder.

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/permissions/cancreate/{type}"

Response

Response Body

SimpleRestResponseType

Defines a REST response having primitives

Status Code

200
200 OK

Example responses

200
{ "response": "true" }

Gets the details of a GRC Object Child Association by the specified ID.

GET /v2/contents/{id}/associations/children/{child_id}

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.get

Request

Path Parameters

id
Required*
string
The GRC Object ID or path. This path can be either a relative path or a full path. Examples:
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*
child_id
Required*
string
The ID of the child object that is associated with this GRC Object.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/associations/children/{child_id}"

Response

Response Body

AssociationNodeType

Defines an objects association type

Status Code

200
200
404
Child ID not found.

Example responses

Status 200: 200 ok Summary

200

{
  "id": "13501",
  "type_definition_id": "7",
  "path": "/_op_sox/Project/Default/IssueActionItems/Test 01/srkissue7_ISSUE_ACTION_ITEM_000001.txt",
  "association_definition_id": "8",
  "type": "child"
}

Status 404: Child ID Not found.

404

{
  "errors": [
    {
      "code": "-2",
      "message": "Not Found - childId : 99999 not found."
    }
  ],
  "status_code": "404"
}

Gets the file contents of a Document as a binary sequence of bytes. The response content type is always a binary stream of content, but the request can specify which MIME type.

GET /v2/contents/{id}/document

Auditing

Calling this method generates the following auditing event.

openpages.file-resource.download

Request

Path Parameters

id
Required*
string
The Document ID or path. Non-document GRC Objects are not supported.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

mime_type
string
MIME Type of the content in the response.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression [A-Za-z0-9 /+-]*
Example: application/octet-stream

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/octet-stream"   "{base_url}/v2/contents/{id}/document?mime_type=application/octet-stream"

Response

Response Body

binary

Content of documents

Status Code

200
200 OK

Example responses

Updates an existing Document attachment instance by sending the content as a raw binary stream. This method is more efficient than encoding the attachment in Base64.

PUT /v2/contents/{id}/document

Auditing

Calling this method generates the following auditing event.

openpages.file-resource.upload

Request

Custom Headers

Content-Type
Required*
string
The MIME type that corresponds to the document content
Content-Length
Required*
string
The length of the document content in bytes

Path Parameters

id
Required*
string
The Document ID or path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

application/octet-streamobject

New contents of the file attachment. Contains the raw bytes of the file with no Base64 encoding.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Content-Length: {content_length}"   --header "Content-Type: application/octet-stream"   "{base_url}/v2/contents/{id}/document"

Response

Status Code

202
Document updated successfully.

No Sample Response

This method does not specify any sample responses.

Get the effective permissions for a user on a GRC Object resource. Users can get their own permissions. A Super Administrator or a Security Administrator can get the permissions for other users using the id parameter.

GET /v2/contents/{id}/permissions/effective

Auditing

Calling this method generates the following auditing event.

openpages.resource-permission.get

Request

Path Parameters

id
Required*
string
GRC Object ID or Path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

user
string
User name or ID to check permissions for. If not specified, defaults to the current user from the session. Only Super Administrators or Security Administrators can specify a value for this parameter. Users without permission that specify a value receive a response of Not Authorized.

Possible values: 1 ≤ length ≤ 320, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/permissions/effective"

Response

Response Body

ResourcePermissionType

Defines a Resource Permission Type Object

Status Code

200
200 OK

Example responses

Status 200: Effective permissions on a GRC Object

200

{
  "folder_id": "7815",
  "security_principal": "user001",
  "can_read": true,
  "can_write": true,
  "can_delete": true,
  "can_associate": true
}

Gets an empty GRC Object template that can be used to create an Object instance. The response body can be used to construct the request body for the POST /contents operation to create a new object.

GET /v2/contents/template

Auditing

Calling this method generates the following auditing event.

openpages.resource-template.get

Request

Query Parameters

type_id
Required*
string
Object Type system name or ID for the new template.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]*
filetype_id
string
For document attachments, specify a file type ID for the File content type. The SOXDocument object type in OpenPages has a set of file types that are allowed to be uploaded. These file types are formats such as MS Word, MS Excel, plain text, and PDF. To get a file type ID for a document object type, the listing of file types and their system IDs can be retrieved by calling GET /v2/types/SOXDocument.

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/template?type_id={type_id}"

Response

Response Body

GrcObjectType

GrcObject Type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "fields": [
    {
      "id": "139",
      "data_type": "STRING_TYPE",
      "name": "OPLC-Std:LCAssignee"
    },
    {
      "id": "141",
      "data_type": "STRING_TYPE",
      "name": "OPLC-Std:LCComment"
    },
    {
      "id": "142",
      "data_type": "DATE_TYPE",
      "name": "OPLC-Std:LCDueDate"
    },
    {
      "id": "3107",
      "data_type": "ENUM_TYPE",
      "name": "OPSS-Issue:Status",
      "enum_value": {
        "id": "8709",
        "name": "Open",
        "localized_label": "Open",
        "index": 2,
        "hidden": false
      }
    }
  ],
  "name": "type name",
  "type_definition_id": "6"
}

Gets the details of a GRC Object Parent Association.

GET /v2/contents/{id}/associations/parents/{parent_id}

Auditing

Calling this method generates the following auditing event.

openpages.resource-association.get

Request

Path Parameters

id
Required*
string
The Object ID or path. This path can be either a relative path or a full path. Examples:
- ID: 3456
- Relative: Issue/Test 01/Issue 1
- Full Path: /_op_sox/Project/Default/Issue/Test 01/Issue 1.txt
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*
parent_id
Required*
string
The ID of the parent object that is associated with this GRC Object.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/associations/parents/{parent_id}"

Response

Response Body

AssociationNodeType

Defines an objects association type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "7821",
  "type_definition_id": "5",
  "path": "/_op_sox/Project/Default/BusinessEntity/Global Financial Services/Asia Pac/Agency Services/Agency Services.txt",
  "association_definition_id": "4",
  "type": "parent"
}

Invokes a Cognos report fragment for a GRC Object by the field name of the fragment. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

GET /v2/contents/{id}/report/{field_name}

Auditing

Calling this method generates the following auditing event.

openpages.report-fragment.report

Request

Path Parameters

id
Required*
string
GRC Object ID or Path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*
field_name
Required*
string
System name of the report fragment field.

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/report/{field_name}"

Response

Response Body

StringFieldType

Defines a String Field type

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "id": "62",
  "data_type": "STRING_TYPE",
  "name": "Comment",
  "has_changed": false,
  "value": ""
}

Gets a list of AssociationAuditLogs for the GRC Object specified by the id parameter. If no filter is specified, then all association logs are retrieved. Use the association_filters parameter to specify filters.

GET /v2/contents/{id}/associations/auditlogs

Auditing

Calling this method generates the following auditing event.

openpages.resource-activity.list

Request

Path Parameters

id
Required*
string
GRC Object ID or Path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

association_filters
string
A comma-delimited list of type names. Use to determine which object types to retrieve from associations.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
startdate
string
Start of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400
enddate
string
End of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/associations/auditlogs?startdate=20220616T075200-0400&enddate=20220616T075200-0400"

Response

Response Body

AssociationAuditLogTypes

Defines Association Audit Log Types

Status Code

200
200

Example responses

Status 200: List of Association Audit Logs for GRC Object

200

{
  "auditlogs": [
    {
      "id": "13501",
      "name": "issue7_ISSUE_ACTION_ITEM_000001.txt",
      "associated_object_type": "SOXTask",
      "modified_by": "user001",
      "modified_date": "2022-06-14T00:28:16.000-0400",
      "status": "ADDED"
    },
    {
      "id": "13501",
      "name": "issue7_ISSUE_ACTION_ITEM_000001.txt",
      "associated_object_type": "SOXTask",
      "modified_by": "user001",
      "modified_date": "2022-06-14T00:28:16.000-0400",
      "status": "ADDED_PRIMARY"
    }
  ]
}

Gets a list of FieldAuditLogs for the GRC Object specified by the id parameter. If no filter is specified, then all field logs are retrieved. Use the field_filters parameter to specify the filters.

GET /v2/contents/{id}/fields/auditlogs

Auditing

Calling this method generates the following auditing event.

openpages.resource-activity.list

Request

Path Parameters

id
Required*
string
GRC Object ID or Path

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

field_filters
string
A comma-delimited list of field system names. Use to determine which field logs to retrieve.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 _@./#&+-]+(,[A-Za-z0-9 _@./#&+-]+)*
start_date
string
Start of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400
end_date
string
End of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/contents/{id}/fields/auditlogs?start_date=20220616T075200-0400&end_date=20220616T075200-0400"

Response

Response Body

FieldAuditLogTypes

Collection of Field Audit Log Types

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "auditlogs": [
    {
      "id": "1104",
      "name": "Assignee",
      "modified_by": "user001",
      "modified_date": "2022-06-10T06:49:28.000-0400",
      "old_value": "",
      "new_value": "jdoe"
    }
  ]
}

Locks a GRC Object.

PUT /v2/contents/{id}/action/lock

Auditing

Calling this method generates the following auditing event.

openpages.resource-lock.set-on

Request

Path Parameters

id
Required*
string
GRC Object ID or Path to lock

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/contents/{id}/action/lock"

Response

Status Code

202
GRC Object locked successfully.

No Sample Response

This method does not specify any sample responses.

Moves a list of GRC Objects to a parent object specified by the id parameter. The moved Objects are created as children of the specified parent.

PUT /v2/contents/{id}/action/move

Auditing

Calling this method generates the following auditing event.

openpages.resource-move.commit

Request

Path Parameters

id
Required*
string
Parent GRC Object ID or Path to move the Objects to

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Request Body

Required*

ActionType

Request body containing the list of Object IDs to be moved and options for the move action

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{ "ids": [ "19001" ], "options": { "include_children": true, "conflict_behavior": "overwrite", "type_definitions": [ "SOXIssue" ], "type_associations": [ { "parent_object_type": "SOXProcess", "child_object_type": "SOXIssue" } ], "auto_name_children": false } }'   "{base_url}/v2/contents/{id}/action/move"

Response

Status Code

202
Moved list of GRC Objects successfully.

No Sample Response

This method does not specify any sample responses.

Overwrites text fields of a object with a specific value. This operation can only be performed by a Super Administrator and cannot be undone. Limitations:

The data type of the fields to be overwritten must be string or long string.
The display type of the fields in any profile must be one of text, text area, rich text, on demand, on demand rich text, or automatic.
For system fields, only the description field and the comment field are allowed.
Encrypted fields are not allowed.
The new value cannot be null or empty.

PUT /v2/contents/{id}/action/overwriteproperties

Auditing

Calling this method generates the following auditing event.

openpages.resource.update

Request

Path Parameters

id
Required*
string
GRC Object ID

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Query Parameters

fields
Required*
string
Comma-delimited list of field definition IDs for the fields to be overwritten.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [0-9]+(,[0-9]+)*
Example: 21,22
value
Required*
string
New value to replace the existing value. Must not be empty.

Possible values: 1 ≤ length ≤ 4096, Value must match regular expression [A-Za-z0-9 _@./#&+-]*

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/contents/{id}/action/overwriteproperties?fields=21,22&value={value}"

Response

Status Code

202
Field values updated successfully.

No Sample Response

This method does not specify any sample responses.

Purges a resource to fully remove all references to the object from the system, including past versions, audit trail, OpenPages storage, and records from reporting periods. This operation can only be performed by a Super Administrator user and cannot be undone. Run this operation sequentially when purging multiple resources. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

DELETE /v2/contents/{id}/action/purge

Auditing

Calling this method generates the following auditing event.

openpages.resource.delete

Request

Path Parameters

id
Required*
string
GRC Object ID or a soft-deleted GRC Object ID

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/contents/{id}/action/purge"

Response

Status Code

204
Resource purged successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Removes all locks from the specified GRC Object and from the hierarchy below the specified GRC Object.

DELETE /v2/contents/{id}/action/remove_all_locks

Auditing

Calling this method generates the following auditing event.

openpages.resource-lock.set-off

Request

Path Parameters

id
Required*
string
GRC Object ID or Path to remove locks from

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/contents/{id}/action/remove_all_locks"

Response

Status Code

204
Unlocked the GRC Object and descendant Objects successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Unlocks a GRC Object if it is locked.

PUT /v2/contents/{id}/action/unlock

Auditing

Calling this method generates the following auditing event.

openpages.resource-lock.set-off

Request

Path Parameters

id
Required*
string
Object ID or Path to unlock

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]*

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/contents/{id}/action/unlock"

Response

Status Code

202
GRC Object unlocked successfully.

No Sample Response

This method does not specify any sample responses.

Gets the root Folder resource for OpenPages with full path of "/"

GET /v2/folders

Auditing

Calling this method generates the following auditing event.

openpages.root-folder.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/folders"

Response

Response Body

FolderTypes

Collection of FolderType Objects

Status Code

200
200

Example responses

Status 200: Root folder resource

200

{
  "folders": [
    {
      "name": "/",
      "id": "1",
      "path": "/",
      "is_folder": true,
      "creation_date": "2022-04-18T22:11:05.000-0400",
      "modified_date": "2022-04-18T22:11:05.000-0400",
      "parent_folder_id": "1",
      "description": "The root storage folder"
    }
  ]
}

Creates a Folder. To use a template folder to construct the request body, see the GET /folders/template operation.

POST /v2/folders

Auditing

Calling this method generates the following auditing event.

openpages.folder.create

Request

Request Body

Required*

FolderType

Create a Folder.

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "testFolder", "path": "testFolder", "description": "TestFolder", "parent_folder_id": "1" }'   "{base_url}/v2/folders"

Response

Response Body

FolderType

Defines an Folder type

Status Code

201
Created Folder

Example responses

Status 201: Created Folder

201

{
  "name": "ActionsFolder",
  "id": "18501",
  "path": "/_op_sox/Project/Default/ActionsFolder",
  "is_folder": true,
  "creation_date": "2022-06-23T01:42:22.000-0400",
  "modified_date": "2022-06-23T01:42:22.000-0400",
  "description": "All actions in this Folder",
  "parent_folder_id": "13",
  "creator": "user01",
  "last_modified_by": "user01"
}

Gets specific Folder resource information by ID.

GET /v2/folders/{folder_id}

Auditing

Calling this method generates the following auditing event.

openpages.folder.get

Request

Path Parameters

folder_id
Required*
string
Folder ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/folders/{folder_id}"

Response

Response Body

FolderType

Defines an Folder type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "Default",
  "id": "13",
  "path": "/_op_sox/Project/Default",
  "is_folder": true,
  "creation_date": "2022-04-18T22:12:56.000-0400",
  "modified_date": "2022-04-18T22:12:56.000-0400",
  "description": "Application Folder",
  "parent_folder_id": "12",
  "creator": "OPSystem",
  "last_modified_by": "OPSystem"
}

Updates an existing Folder.

PUT /v2/folders/{folder_id}

Auditing

Calling this method generates the following auditing event.

openpages.folder.update

Request

Path Parameters

folder_id
Required*
string
ID of Folder to be updated

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Request Body

Required*

FolderType

Update an existing Folder

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "id": "12595", "name": "testFolder", "path": "testFolder", "description": "TestFolder updated description", "parent_folder_id": "1" }'   "{base_url}/v2/folders/{folder_id}"

Response

Response Body

FolderType

Defines an Folder type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "ActionsFolder",
  "id": "18501",
  "path": "/_op_sox/Project/Default/ActionsFolder",
  "is_folder": true,
  "creation_date": "2022-06-23T01:42:22.000-0400",
  "modified_date": "2022-06-23T01:46:45.000-0400",
  "description": "All department actions in this Folder",
  "parent_folder_id": "13",
  "creator": "user01",
  "last_modified_by": "user01"
}

Deletes a Folder and all of its contents. Cannot be undone.

DELETE /v2/folders/{folder_id}

Auditing

Calling this method generates the following auditing event.

openpages.folder.delete

Request

Path Parameters

folder_id
Required*
string
ID of Folder to delete

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/folders/{folder_id}"

Response

Status Code

204
The folder was deleted successfully. No Content.

No Sample Response

This method does not specify any sample responses.

Gets the effective permissions (ACL) for a user on a GRC Object resource. Example path for GET request: /folders/1234/effectivePermissions?user=bill

GET /v2/folders/{folder_id}/permissions/effective

Auditing

Calling this method generates the following auditing event.

openpages.folder-permission.get

Request

Path Parameters

folder_id
Required*
string
ID of Folder to get permissions from.

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

user
string
User name or ID. If a value is not specified, the effective permissions for the current user are retrieved.

Possible values: 1 ≤ length ≤ 320, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/folders/{folder_id}/permissions/effective"

Response

Response Body

ResourcePermissionType

Defines a Resource Permission Type Object

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "folder_id": "13",
  "security_principal": "user01",
  "can_read": true,
  "can_write": true,
  "can_delete": true,
  "can_associate": true
}

Gets an empty Folder template that can be used to create a new folder. The response body can be used to construct the request body for a new folder for the POST /v2/folders endpoint.

GET /v2/folders/template

Auditing

Calling this method generates the following auditing event.

openpages.folder-template.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/folders/template"

Response

Response Body

FolderType

Defines an Folder type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "foldername",
  "id": "-1",
  "is_folder": true,
  "parent_folder_id": "1"
}

Gets all resources contained in a folder. Results can be either GRC Object content or other Folders.

GET /v2/folders/{folder_id}/resources

Auditing

Calling this method generates the following auditing event.

openpages.folder.list

Request

Path Parameters

folder_id
Required*
string
ID of Folder to get contained resources from.

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

include_containees
string
Which types of contained resources to return.

Allowable values: [folder,grcobject,both]
Default: both
offset
int32
0-based index of the first query result.

Default: 0
limit
int32
Specifies the desired maximum number of results per page.

Possible values: value ≤ 1000
Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/folders/{folder_id}/resources"

Response

Response Body

ResourceTypes

Collection of ResourceType Objects

Status Code

200
200

Example responses

Status 200: List of contained resources that can be GRCObjectType or FolderType

200

{
  "resources": [
    {
      "name": "BusinessEntity",
      "id": "14",
      "path": "/_op_sox/Project/Default/BusinessEntity",
      "is_folder": true,
      "creation_date": "2022-04-19T02:12:56.000Z",
      "modified_date": "2022-05-03T11:12:34.000-0400",
      "description": "Application Folder",
      "parent_folder_id": "13",
      "creator": "OPSystem",
      "last_modified_by": "OpenPagesAdministrator"
    },
    {
      "name": "ICDocumentation",
      "id": "15",
      "path": "/_op_sox/Project/Default/ICDocumentation",
      "is_folder": true,
      "creation_date": "2022-04-19T02:12:57.000Z",
      "modified_date": "2022-05-03T11:12:50.000-0400",
      "description": "Application Folder",
      "parent_folder_id": "13",
      "creator": "OPSystem",
      "last_modified_by": "OpenPagesAdministrator"
    },
    {
      "name": "Issue",
      "id": "17",
      "path": "/_op_sox/Project/Default/Issue",
      "is_folder": true,
      "creation_date": "2022-04-19T02:12:57.000Z",
      "modified_date": "2022-04-18T22:12:57.000-0400",
      "description": "Application Folder",
      "parent_folder_id": "13",
      "creator": "OPSystem",
      "last_modified_by": "OPSystem"
    }
  ]
}

Gets the latest specific Process instance information by Process Type ID.

GET /v2/processes/latest/{process_type_id}

Auditing

Calling this method generates the following auditing event.

openpages.process.get

Request

Path Parameters

process_type_id
Required*
string
Process Type ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/processes/latest/{process_type_id}"

Response

Response Body

ProcessInfoType

Defines a Process Info type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "process_id": "2410",
  "name": "Start workflows in bulk",
  "description": " ",
  "process_type_id": "280",
  "finished": true,
  "created_on": "2022-06-23T00:00:01.007-0400",
  "created_by": "OPSystem",
  "status": "status_finished_success",
  "percent_complete": 100,
  "child_processes": []
}

Gets a specific Process instance by ID.

GET /v2/processes/{process_id}

Auditing

Calling this method generates the following auditing event.

openpages.process.get

Request

Path Parameters

process_id
Required*
string
Process instance ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

include_child_processes
boolean
Specifies whether the response should include child processes

Default: true

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/processes/{process_id}"

Response

Response Body

ProcessInfoType

Defines a Process Info type

Status Code

200
200

Example responses

Status 200: Process details.

200

{
  "process_id": "1",
  "name": "OpenPagesAdministrator-1650335156093",
  "description": "Import Migration File",
  "process_type_id": "120",
  "finished": true,
  "created_on": "2022-04-18T22:26:00.074-0400",
  "created_by": "OpenPagesAdministrator",
  "status": "status_finished_success",
  "percent_complete": 100,
  "child_processes": []
}

Terminates a Process instance. Stops the process instance execution and cannot be undone.

PUT /v2/processes/{process_id}

Auditing

Calling this method generates the following auditing event.

openpages.process.stop

Request

Path Parameters

process_id
Required*
string
Process instance ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

action
Required*
string
The terminate action to perform

Allowable values: [terminate]

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/processes/{process_id}?action=terminate"

Response

Status Code

202
Process successfully terminated.
400
400

Example responses

Status 400: Provide a valid action name

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-2",
      "message": "Bad Request - Please provide a valid action name."
    }
  ]
}

Gets the Process Logs for a Process instance. Up to 1,000 process logs can be returned in one request. Use paging parameters to retrieve more logs.

GET /v2/processes/{process_id}/logs

Auditing

Calling this method generates the following auditing event.

openpages.process-log.list

Request

Path Parameters

process_id
Required*
string
Process instance ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

include_localized_status
boolean
Specifies whether the response should include localized status labels

Default: false
offset
int32
Number of log records to skip

Default: 0
limit
int32
Page size

Possible values: value ≤ 1000
Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/processes/{process_id}/logs"

Response

Response Body

ProcessLogTypes

Collection of ProcessLogType Objects

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "process_logs": [
    {
      "process_log_id": "3346",
      "process_id": "1",
      "status": "status_finished_success",
      "status_message": "Import Migration File: Completed",
      "end_time": "2022-04-18T23:08:07.516-0400",
      "error_message_id": "",
      "localized_status": ""
    },
    {
      "process_log_id": "3345",
      "process_id": "1",
      "status": "status_running",
      "status_message": "Import Migration File: [user01-1650335156093] : Finished the import process...",
      "start_time": "2022-04-18T23:08:07.447-0400",
      "error_message_id": "",
      "localized_status": ""
    }
  ]
}

Gets all Process Types in the Long Running Process Framework (LRPF).

GET /v2/processes/processtypes

Auditing

Calling this method generates the following auditing event.

openpages.process-type.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/processes/processtypes"

Response

Response Body

ProcessTypeTypes

Collection of ProcessTypeType Objects

Status Code

200
All Process Types

Example responses

Status 200: 200 ok Summary

200

{
  "processtypes": [
    {
      "process_type_id": "230",
      "name": "Global Search",
      "description": "Global Search",
      "default_time_seconds": 3600,
      "is_multiple_instance": false,
      "is_terminate_upon_start": true
    },
    {
      "process_type_id": "48",
      "name": "Associated Object Move",
      "description": "Associated Object Move",
      "default_time_seconds": 900,
      "is_multiple_instance": true,
      "is_terminate_upon_start": true
    },
    {
      "process_type_id": "350",
      "name": "Encrypt With External Key",
      "description": "Encrypt With External Key",
      "default_time_seconds": 18000,
      "is_multiple_instance": false,
      "is_terminate_upon_start": true
    }
  ]
}

Gets a list of Process instances by ID.

GET /v2/processes

Auditing

Calling this method generates the following auditing event.

openpages.process.list

Request

Query Parameters

process_id
string
Process instance ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*
parent_process_id
string
The parent Process ID of queried processes

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*
process_type_id
string
The Process type id of queried processes

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*
status
string
The Process status of queried processes in a comma-separated list

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z_-]*
created_on_begin
string
To define a range of dates when the processes were created, specify a start date and time for the range. Use the XMLGregorianCalendar pattern "yyyyMMdd'T'HHmmssZ".

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400
created_on_end
string
To define a range of dates when the processes were created, specify an end date and time for the range. Use the XMLGregorianCalendar pattern "yyyyMMdd'T'HHmmssZ".

Possible values: length = 20, Value must match regular expression [0-9]{4}[0-9]{2}[0-9]{2}[T][0-9]{2}[0-9]{2}[0-9]{2}[+|-][0-9]{4}
Example: 20220616T075200-0400
created_by
string
The user who created the queried processes

Possible values: 1 ≤ length ≤ 320, Value must match regular expression [A-Za-z0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/processes?created_on_begin=20220616T075200-0400&created_on_end=20220616T075200-0400"

Response

Response Body

ProcessInfoTypes

Collection of ProcessTypeType

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "processes": [
    {
      "process_id": "2410",
      "name": "Start workflows in bulk",
      "description": " ",
      "process_type_id": "280",
      "finished": true,
      "created_on": "2022-06-23T00:00:01.007-0400",
      "created_by": "OPSystem",
      "status": "status_finished_success",
      "percent_complete": 100,
      "child_processes": []
    },
    {
      "process_id": "2409",
      "name": "Start workflows in bulk",
      "description": " ",
      "process_type_id": "280",
      "finished": true,
      "created_on": "2022-06-23T00:00:00.978-0400",
      "created_by": "OPSystem",
      "status": "status_finished_success",
      "percent_complete": 100,
      "child_processes": []
    }
  ]
}

Gets the results of a query on content based on SQL-like syntax with parameters passed by query. Paging of results is supported. The default page size is 50. The default page size can be modified with the /OpenPages/Platform/API/Query/Default PageSize registry setting. Results honor the current user's security permissions including role-based and security rules. To support proper pagination, results for unordered queries are ordered by the first column specified. This allows consistent pagination with repeated executions of the same query. Important: When there are fields on the object type that are excluded by the reporting schema, define the select statements using explicit column names that return the subset of fields that you require. Do not use select * because it is not supported.When querying data with single quote (') in a LIKE condition, make sure to escape the single quote with backslash (\).

GET /v2/query

Auditing

Calling this method generates the following auditing event.

openpages.resource.query

Request

Query Parameters

q
Required*
string
Query statement. Is required and must follow Query-Service syntax.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 /_.-]
Example: SELECT [Name] FROM [SOXBusEntity]
offset
int32
Number of results to be skipped. Used for paging.

Default: 0
case_insensitive
boolean
Specify if string comparisons should be case-insensitive. Applies to all comparisons in WHERE clause.

Default: false
limit
int32
Number of results to return, starting from offset.
max_rows
int32
Maximum number of results the query service retrieves from the database. Use 0 for all rows.

Default: 0
honor_primary
boolean
If JOIN syntax is used between Object Types, specifies whether to restrict to only include primary associations.

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/query?q=SELECT [Name] FROM [SOXBusEntity]"

Response

Response Body

QueryResultTypes

Defines query result type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "definitions": [
    {
      "id": "28",
      "name": "Resource ID",
      "data_type": "ID_TYPE"
    }
  ],
  "rows": [
    {
      "fields": [
        {
          "name": "Resource ID",
          "value": "48"
        }
      ]
    },
    {
      "fields": [
        {
          "name": "Resource ID",
          "value": "8002"
        }
      ]
    }
  ]
}

Service to query content based on SQL-like syntax using POST method. Can use when query statement is lengthy or cannot be encoded. Paging of results is supported. The default page size is 50. The default page size can be modified with the /OpenPages/Platform/API/Query/Default PageSize registry setting. Results honor the current user's security permissions including role-based and security rules. To support proper pagination, results for unordered queries are ordered by the first column specified. This allows consistent pagination with repeated executions of the same query. Important: When there are fields on the object type that are excluded by the reporting schema, define the select statements using explicit column names that return the subset of fields that you require. Do not use select * because it is not supported.When querying data with single quote (') in a LIKE condition, make sure to escape the single quote with backslash (\).Example: With python code use \\', while with curl command or any other API test tools the single quotes needs to be escaped with three backslash.

POST /v2/query

Auditing

Calling this method generates the following auditing event.

openpages.resource.query

Request

Request Body

Required*

QueryType

Defines a query type

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "statement": " SELECT [Resource ID] FROM [SOXDocument] ", "offset": 0, "max_rows": 2, "limit": 50, "case_insensitive": false, "honor_primary": false }'   "{base_url}/v2/query"

Response

Response Body

QueryResultTypes

Defines query result type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "definitions": [
    {
      "id": "28",
      "name": "Resource ID",
      "data_type": "ID_TYPE"
    }
  ],
  "rows": [
    {
      "fields": [
        {
          "name": "Resource ID",
          "value": "48"
        }
      ]
    },
    {
      "fields": [
        {
          "name": "Resource ID",
          "value": "8002"
        }
      ]
    }
  ]
}

Gets the results of a Global Search of all GRC content. The search is performed by matching search terms across any field in the current user's profile and returns a list of results based on a search ranking. The results are sorted with the most relevant first. A specific range can be requested, and separate requests are used to retrieve subsequent ranges. The results are limited to the setting 'Platform / Search / Request / Result Cache Size'. Ranges beyond this size are not allowed. The search can be scoped by a list of Types, or all Types if not specified. Results honor the current user's security permissions including role-based and security rules.

Provides a REST end-point that can be compatible with a Dojo JsonRestStore client. The JsonRestStore follows RFC 2616 whenever possible to define interaction with server. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

GET /v2/search

Auditing

Calling this method generates the following auditing event.

openpages.resource.search

Request

Custom Headers

Range
string
For paging a client may include a HTTP Range header with an items range unit specifying the range. Example: items=0-24

Possible values: 9 ≤ length ≤ 20, Value must match regular expression items=([0-9]+)-([0-9]+)

Query Parameters

q
Required*
string
Search terms

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9 _@./#&+-]*
range
string
Range of search results to return. If present, uses the value from the HTTP Range header. Otherwise, uses the value of this parameter. Format of range is start#-end#

Possible values: 3 ≤ length ≤ 6, Value must match regular expression [0-9 -]*
Default: 0-9
types
string
Object Types to include in search. All possible types are included if not specified. Format of types is a comma-delimited list of Object Type names or IDs. Deprecated in 7.3, Instead use 'fot' parameter.

Possible values: 1 ≤ length ≤ 512, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
Example: SOXRisk,SOXProcess,SOXControll
mode
string
Global Search mode. Reserved for future use.

Allowable values: [normal]
Default: normal
fot
string
Faceted Search by Object Types. All possible types are included if not specified. Format of types is comma-delimited list of Object Type names or IDs. If both 'fot' and 'types' are present, then types is ignored.

Possible values: 1 ≤ length ≤ 512, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
Example: SOXRisk,SOXProcess,SOXControll
fur
string
Faceted Search by Users. Use a semicolon to represent more than one user facet to search on. Syntax: {!T A}[DATA];{!T A}[DATA]
- !T = Type of user facet
  - !c = creator
  - !l = last modified by
  - !o = user selected in fields
- A = Action on user facet
  - m = me
  - o = others, specify in DATA
- DATA = Data of user facet (comma-delimited list of user names or IDs)
Possible values: 1 ≤ length ≤ 512, Value must match regular expression [A-Za-z0-9 {}\[\]!,;]*
Example: {!c m}[orm];{!l o}[alaudit,sueaudit,charlieaudit]
fdt
string
Faceted Search by Date. Use a semicolon to represent more than one date facet. Syntax: {!T A}[DATA];{!T A}[DATA]
- !T = Type of date facet
  - !c = creation date
  - !l = last modified date
  - !o = date in fields
- A = Action on date facet
  - o = on date
  - r = date range
  - p = previous days
  - n = next days
- DATA = Data of date facet
  - YYYY-MM-DD = a specific date
  - YYYY-MM-DD TO YYYY-MM-DD = a date range
Possible values: 1 ≤ length ≤ 512, Value must match regular expression [A-Za-z0-9 {}\[\]!-;]*
Example: {!c o}[2015-06-01];{!l r}[2016-01-01 TO 2016-06-31];{!o n}[7]
ffp
string
Faceted Search by Folder Path. Use relative paths starting from below the Object type root folder.

Possible values: 1 ≤ length ≤ 512, Value must match regular expression [A-Za-z0-9 /;]*
Example: /BE1/L1/Issue 84
fmt
string
Faceted Search by MIME type. Applies to file attachment search. Comma-delimited list of MIME Media types.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression [A-Za-z0-9 /-;]*
Example: application/pdf

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/search?q={q}&types=SOXRisk,SOXProcess,SOXControll&fot=SOXRisk,SOXProcess,SOXControll&fur={!c m}[orm];{!l o}[alaudit,sueaudit,charlieaudit]&fdt={!c o}[2015-06-01];{!l r}[2016-01-01 TO 2016-06-31];{!o n}[7]&ffp=/BE1/L1/Issue 84&fmt=application/pdf"

Response

Response Body

SearchResponseType

Defines a Search Response Type

Status Code

200
Search results
400
Search parameters not provided in request body

Example responses

Status 200: 200 ok Summary

200

{
  "estimated_results": 10,
  "result_list": [
    {
      "id": "7704",
      "name": "Issue Action Item 8",
      "description": "This is an example of free text.",
      "path": "Test 21 / Test 22 / Issue Action Item 8",
      "title": "Example title",
      "object_type_id": "7",
      "object_type_name": "SOXTask",
      "object_type_label": "Action Item",
      "parent_folder_id": "6192",
      "custom_display_fields": [
        {
          "field_label": "Additional Description",
          "display_type_id": 8,
          "value": "This is an example of free text."
        }
      ]
    },
    {
      "id": "7707",
      "name": "Issue Action Item 11",
      "description": "This is an example of free text.",
      "path": "Test 31 / Test 32 / Issue Action Item 11",
      "title": "Another example title",
      "object_type_id": "7",
      "object_type_name": "SOXTask",
      "object_type_label": "Action Item",
      "parent_folder_id": "6291",
      "custom_display_fields": [
        {
          "field_label": "Additional Description",
          "display_type_id": 8,
          "value": "This is an example of free text."
        }
      ]
    }
  ]
}

Status 400: Invalid Search parameters

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-24007",
      "text": "java.lang.IllegalArgumentException: Search parameter 'q' is required and cannot be empty",
      "message": "OP-24007: Please enter valid search terms. [VLGB93UGYELA]",
      "status": "Bad Request"
    }
  ]
}

Global Search of all GRC data. The search is performed by matching search terms across any field in the current user's profile and returns a list of results based on a search ranking (most relevant first). A specific range can be requested, and separate requests are used to retrieve subsequent ranges. The results are limited to the setting 'Platform / Search / Request / Result Cache Size'. Ranges beyond this size are not allowed. The search can be scoped by a list of Types, or all Types if not specified. Results honor the current user's security permissions including role-based and security rules. This operation is available only for OpenPages (on premise), OpenPages on Cloud, and OpenPages for Cloud Pak for Data. It is not available for OpenPages as a Service.

POST /v2/search

Auditing

Calling this method generates the following auditing event.

openpages.resource.search

Request

Request Body

Required*

SearchType

Search parameters

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "q": "Issue Actions", "page_size": 10 }'   "{base_url}/v2/search"

Response

Response Body

SearchResponseType

Defines a Search Response Type

Status Code

200
Search results
400
Search parameters not provided in request body

Example responses

Status 200: 200 ok Summary

200

{
  "estimated_results": 10,
  "result_list": [
    {
      "id": "7704",
      "name": "Issue Action Item 8",
      "description": "This is an example of free text.",
      "path": "Test 21 / Test 22 / Issue Action Item 8",
      "title": "Example title",
      "object_type_id": "7",
      "object_type_name": "SOXTask",
      "object_type_label": "Action Item",
      "parent_folder_id": "6192",
      "custom_display_fields": [
        {
          "field_label": "Additional Description",
          "display_type_id": 8,
          "value": "This is an example of free text."
        }
      ]
    },
    {
      "id": "7707",
      "name": "Issue Action Item 11",
      "description": "This is an example of free text.",
      "path": "Test 31 / Test 32 / Issue Action Item 11",
      "title": "Another example title",
      "object_type_id": "7",
      "object_type_name": "SOXTask",
      "object_type_label": "Action Item",
      "parent_folder_id": "6291",
      "custom_display_fields": [
        {
          "field_label": "Additional Description",
          "display_type_id": 8,
          "value": "This is an example of free text."
        }
      ]
    }
  ]
}

Status 400: Invalid search parameters

400

{
  "status_code": "400",
  "errors": [
    {
      "code": "-24007",
      "text": "java.lang.IllegalArgumentException: The request body must contain the search parameters for POST method.",
      "message": "OP-24007: Please enter valid search terms. [VLGD15A6XQ4Z]",
      "status": "Bad Request"
    }
  ]
}

Runs any defined regulatory events routing rules that might apply to the given object IDs. If there are no rules applicable for an object, it's still considered successful.

POST /v2/rules/run

Auditing

Calling this method generates the following auditing event.

openpages.rule.evaluate

Request

Request Body

Required*

tbrules_runrules_request_type

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "object_ids": [ "12068", "134537", "/_op_sox/Project/Default/ICDocumentation/Regulatory Events/Library/RCM/RegEvents/TRRIRegEvents/I7D8E68203DD311EAA9C9B7A1807E26E0.txt", "12069" ] }'   "{base_url}/v2/rules/run"

Response

Response Body

tbrules_runrules_response_type

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "successful_objects": [
    "12068",
    "12069"
  ],
  "failed_objects": [
    {
      "object_id": "134537",
      "failure_reason": "OP-03100: Resource 134537 was not found. [V0L6DV3F7QJZ]"
    },
    {
      "object_id": "/_op_sox/Project/Default/ICDocumentation/Regulatory Events/Library/RCM/RegEvents/TRRIRegEvents/I7D8E68203DD311EAA9C9B7A1807E26E0.txt",
      "failure_reason": "OP-03100: Resource /_op_sox/Project/Default/ICDocumentation/Regulatory Events/Library/RCM/RegEvents/TRRIRegEvents/I7D8E68203DD311EAA9C9B7A1807E26E0.txt was not found. [V0L6DV3L646E]"
    }
  ]
}

Gets an association definition for an Object Type by the association's ID.

GET /v2/types/{type_id}/associations/{association_id}

Auditing

Calling this method generates the following auditing event.

openpages.object-type-association.get

Request

Path Parameters

type_id
Required*
string
Object Type ID or Object Type system name

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9]*
association_id
Required*
string
Association definition ID

Possible values: 1 ≤ length ≤ 31, Value must match regular expression [0-9]*

Query Parameters

include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/types/{type_id}/associations/{association_id}"

Response

Response Body

AssociationDefinitionType

Defines an association definition type

Status Code

200
200 OK
404
Object Type not found

Example responses

Status 200: 200 ok Summary

200

{
  "id": "2",
  "name": "SOXProject",
  "localized_label": "SOXProject",
  "localized_labels": [
    {
      "locale_iso_code": "es_ES",
      "localized_label": "SOXProject"
    },
    {
      "locale_iso_code": "en_US",
      "localized_label": "SOXProject"
    }
  ],
  "localized_plural_label": "SOXProject",
  "localized_plural_labels": [
    {
      "locale_iso_code": "es_ES",
      "localized_label": "SOXProject"
    },
    {
      "locale_iso_code": "en_US",
      "localized_label": "SOXProject"
    }
  ],
  "association_definition_id": "2",
  "max": 2147483647,
  "min": 1,
  "is_enabled": true,
  "relationship": "Parent",
  "enabled": true
}

Status 404: association_id Not found

404

{
  "status_code": "404",
  "errors": [
    {
      "code": "-2",
      "message": "Not Found - associationId : 1021 not found."
    }
  ]
}

Gets all Non provisioned Solutions Usage.

GET /v2/types/usages/unclaimed

Auditing

Calling this method generates the following auditing event.

openpages.object-type-unclaimed.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/types/usages/unclaimed"

Response

Response Body

SolutionUsageList

Collection of Solution usage

Status Code

200
200 OK
404
Solution usage not found

Example responses

Status 200: 200 ok Summary

200

{
  "solution_usages": [
    {
      "solution_name": "Custom Object",
      "asset_types": [
        {
          "name": "LevelTwo",
          "labels": {
            "de_DE": "LevelTwo",
            "en_CA": "LevelTwo",
            "en_GB": "LevelTwo",
            "en_US": "Level Two",
            "es_ES": "LevelTwo",
            "fr_FR": "LevelTwo",
            "it_IT": "LevelTwo",
            "ja_JP": "LevelTwo",
            "pt_BR": "LevelTwo",
            "zh_CN": "LevelTwo",
            "zh_TW": "LevelTwo"
          }
        },
        {
          "name": "LevelOne",
          "labels": {
            "de_DE": "LevelOne",
            "en_CA": "LevelOne",
            "en_GB": "LevelOne",
            "en_US": "Level One",
            "es_ES": "LevelOne",
            "fr_FR": "LevelOne",
            "it_IT": "LevelOne",
            "ja_JP": "LevelOne",
            "pt_BR": "LevelOne",
            "zh_CN": "LevelOne",
            "zh_TW": "LevelOne"
          }
        }
      ]
    }
  ]
}

Status 404: Solution Usage Not found

404

{
  "status_code": "404",
  "errors": [
    {
      "code": "-1024",
      "message": "Not Found - Solution Usage Not found."
    }
  ]
}

Gets an Object Type. Use optional parameters to control what data is returned.

GET /v2/types/{type_id}

Auditing

Calling this method generates the following auditing event.

openpages.object-type.get

Request

Path Parameters

type_id
Required*
string
Object Type ID or Object Type system name

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9]*

Query Parameters

include_field_definitions
boolean
Include Field definitions

Default: true
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/types/{type_id}"

Response

Response Body

type_definition_type

Defines a TypeDefinition type

Status Code

200
200 OK
404
Object Type not found

Example responses

Status 200: 200 ok Summary

200

{
  "id": "6",
  "name": "SOXIssue",
  "localized_label": "Issue",
  "localized_labels": [
    {
      "locale_iso_code": "es_ES",
      "localized_label": "Problema"
    },
    {
      "locale_iso_code": "en_US",
      "localized_label": "Issue"
    }
  ],
  "localized_plural_label": "Issues",
  "localized_plural_labels": [
    {
      "locale_iso_code": "es_ES",
      "localized_label": "Problemas"
    },
    {
      "locale_iso_code": "en_US",
      "localized_label": "Issues"
    }
  ],
  "description": "OpenPages GRC Object Type",
  "jsp_path": "/propertyForm/renderProperties.jsp",
  "root_folder_path": "/_op_sox/Project/Default/Issue",
  "root_folder_id": "17",
  "field_definitions": [
    {
      "id": "28",
      "name": "Resource ID",
      "localized_label": "Resource ID",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Resource ID"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Resource ID"
        }
      ],
      "localized_guidance": "Resource ID",
      "localized_guidances": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Resource ID"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Resource ID"
        }
      ],
      "data_type": "ID_TYPE",
      "required": true,
      "description": "Resource ID",
      "computed": false,
      "read_only": true,
      "dependencies": [],
      "enum_values": [],
      "is_hierarchical": false
    },
    {
      "id": "62",
      "name": "Comment",
      "localized_label": "Comment",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Comentario"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Comment"
        }
      ],
      "localized_guidance": "Comment",
      "localized_guidances": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Comentario"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Comment"
        }
      ],
      "data_type": "STRING_TYPE",
      "required": false,
      "description": "Version Comment",
      "computed": false,
      "read_only": false,
      "dependencies": [],
      "enum_values": [],
      "is_hierarchical": false
    }
  ],
  "file_types": []
}

Status 404: Object Type not found

404

{
  "status_code": "404",
  "errors": [
    {
      "code": "-1024",
      "message": "Not Found - OP-01024: The requested Object Type was not found. [VV5GJGMFW3SQ]"
    }
  ]
}

Gets all Object Type association definitions for a GRC Object Type in the schema. Use the association_type parameter to retrieve only parent or child association definitions.

GET /v2/types/{type_id}/associations

Auditing

Calling this method generates the following auditing event.

openpages.object-type-association.list

Request

Path Parameters

type_id
Required*
string
GRC Object Type ID or GRC Object Type system name

Possible values: 1 ≤ length ≤ 256, Value must match regular expression [A-Za-z0-9]*

Query Parameters

include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale

Default: false
association_type
string
Filters object associations based on association type. Value can be parent or child.

Allowable values: [parent,child]

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/types/{type_id}/associations"

Response

Response Body

AssociationDefinitionTypes

Defines Association Definition Types

Status Code

200
200 OK
404
Object Type not found

Example responses

Status 200: 200 ok Summary

200

{
  "associations": [
    {
      "id": "2",
      "name": "SOXProject",
      "localized_label": "SOXProject",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "SOXProject"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "SOXProject"
        }
      ],
      "localized_plural_label": "SOXProject",
      "localized_plural_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "SOXProject"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "SOXProject"
        }
      ],
      "association_definition_id": "2",
      "max": 2147483647,
      "min": 1,
      "is_enabled": true,
      "relationship": "Parent",
      "enabled": true
    },
    {
      "id": "5",
      "name": "SOXBusEntity",
      "localized_label": "Business Entity",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Entidad de negocios"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Business Entity"
        }
      ],
      "localized_plural_label": "Business Entities",
      "localized_plural_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Entidades de negocios"
        },
        {
          "locale_iso_code": "en_US",
          "localized_label": "Business Entities"
        }
      ],
      "association_definition_id": "4",
      "max": 2147483647,
      "min": 1,
      "is_enabled": true,
      "relationship": "Parent",
      "enabled": true
    }
  ]
}

Status 404: Object Type not found

404

{
  "status_code": "404",
  "errors": [
    {
      "code": "-1024",
      "message": "Not Found - OP-01024: The requested Object Type was not found. [VV5GSZHSKA5T]"
    }
  ]
}

Gets a list of all GRC Object Types. Use optional parameters to control data returned.

GET /v2/types

Auditing

Calling this method generates the following auditing event.

openpages.object-type.list

Request

Query Parameters

include_field_definitions
boolean
Include Field definitions

Default: false
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/types"

Response

Response Body

TypeDefinitionTypes

Collection of TypeDefinition Types

Status Code

200
List all Object Types.

Example responses

Status 200: List all Object Types

200

{
  "types": [
    {
      "id": "23",
      "name": "Assertion",
      "localized_label": "Assertion",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Problema"
        },
        {
          "locale_iso_code": "de_DE",
          "localized_label": "Problem"
        }
      ],
      "localized_plural_label": "Assertions",
      "localized_plural_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Problemas"
        },
        {
          "locale_iso_code": "de_DE",
          "localized_label": "Probleme"
        }
      ],
      "description": "Unified Object Type",
      "jsp_path": "/propertyForm/renderProperties.jsp",
      "root_folder_path": "/_op_sox/Project/Default/ICDocumentation/Assertions",
      "root_folder_id": "502",
      "field_definitions": [
        {
          "id": "28",
          "name": "Resource ID",
          "localized_label": "Resource ID",
          "localized_guidance": "Resource ID",
          "localized_guidances": [],
          "data_type": "ID_TYPE",
          "required": true,
          "description": "Resource ID",
          "computed": false,
          "read_only": true,
          "dependencies": [],
          "enum_values": [],
          "is_hierarchical": false
        },
        {
          "id": "62",
          "name": "Comment",
          "localized_label": "Comment",
          "localized_guidance": "Comment",
          "localized_guidances": [],
          "data_type": "STRING_TYPE",
          "required": false,
          "description": "Version Comment",
          "computed": false,
          "read_only": false,
          "dependencies": [],
          "enum_values": [],
          "is_hierarchical": false
        }
      ],
      "file_types": []
    },
    {
      "id": "24",
      "name": "Attestation",
      "localized_label": "Attestation",
      "localized_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Problema"
        },
        {
          "locale_iso_code": "de_DE",
          "localized_label": "Problem"
        }
      ],
      "localized_plural_label": "Attestations",
      "localized_plural_labels": [
        {
          "locale_iso_code": "es_ES",
          "localized_label": "Problemas"
        },
        {
          "locale_iso_code": "de_DE",
          "localized_label": "Probleme"
        }
      ],
      "description": "Unified Object Type",
      "jsp_path": "/propertyForm/renderProperties.jsp",
      "root_folder_path": "/_op_sox/Project/Default/ICDocumentation/Attestations",
      "root_folder_id": "503",
      "field_definitions": [
        {
          "id": "28",
          "name": "Resource ID",
          "localized_label": "Resource ID",
          "localized_guidance": "Resource ID",
          "localized_guidances": [],
          "data_type": "ID_TYPE",
          "required": true,
          "description": "Resource ID",
          "computed": false,
          "read_only": true,
          "dependencies": [],
          "enum_values": [],
          "is_hierarchical": false
        },
        {
          "id": "62",
          "name": "Comment",
          "localized_label": "Comment",
          "localized_guidance": "Comment",
          "localized_guidances": [],
          "data_type": "STRING_TYPE",
          "required": false,
          "description": "Version Comment",
          "computed": false,
          "read_only": false,
          "dependencies": [],
          "enum_values": [],
          "is_hierarchical": false
        }
      ],
      "file_types": []
    }
  ]
}

Processes a bulk request.

POST /v2/scim/Bulk

Request

Request Body

Required*

SCIMBulkRequest

Processes a bulk request.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "schemas": [] }'   "{base_url}/v2/scim/Bulk"

Response

Response Body

BulkResponse

Status Code

200
200 OK

Example responses

Gets the top-level groups in the system. Only Security Administrators can view groups. Use filters and response attributes to limit the list of users to return. Pagination and Sort parameters can be specified in the Query URL. For filter syntax, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2 . Following attribute operators are supported 'eq', 'ne', 'co', 'sw', 'ew', 'gt', 'ge', 'lt', 'le'. 'pr' is not supported currently. All Logical operators are supported. Query filter can be defined on following group core attributes - 'id', 'displayName'. Following group extension attributes can also be used in defining filters - 'description'. Extension attributes MUST be prefixed with extenstion URN when used in filters. Examples:-

filter=displayName eq "bjensen"

filter=displayName co "doe" and urn:ietf:params:scim:schemas:extension:openpages:GroupExtension:description eq "Group created through onboarding module"

To select resource attributes to be returned, use 'attributes' query parameter. For 'attributes' notation, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.5 This query parameter is a multi-valued list of strings. 'excludedAttributes' is not supported. While listing group extension attributes in the 'attributes' parameter, schema URN can be omitted. Examples :-

attributes=displayName,description

attributes=displayName,members,description

To sort the query results, specify 'sortBy' and 'sortOrder' query parameters. In 'sortBy' parameter, the same list of attributes as in query filters are supported. Examples:-

sortBy=displayName&sortOrder=descending

sortBy=urn:ietf:params:scim:schemas:extension:openpages:GroupExtension:description&sortOrder=ascending

To page through large number of results, use pagination parameters of 'startIndex' and 'count'. refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4

GET /v2/scim/Groups

Auditing

Calling this method generates the following auditing event.

openpages.group.list

Request

Query Parameters

filter
string
Filter expression used to request a subset of resources

Example: filter=displayName eq "bjensen"
attributes
string
Comma-separated list of resource attribute names to be returned in response

Default:
Example: attributes=displayName,description
sortOrder
string
Specifies sort order. Values are 'ascending' or 'descending'.

Default: ascending
sortBy
string
Resource attribute name to sort on.
startIndex
int32
1-based index of the first query result

Default: 1
count
int32
Specifies the desired maximum number of results per page

Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Groups?filter=filter=displayName eq \"bjensen\"&attributes=attributes=displayName,description"

Response

Response Body

SCIMGroup

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "id": "3057",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
      ],
      "displayName": "Rest_Test_Group_Filter-982a82cab59b-00a1",
      "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
        "isEditable": true,
        "adminLevel": 0
      }
    },
    {
      "id": "3058",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
      ],
      "displayName": "Rest_Test_Group_Filter-982a82cab59b-00a2",
      "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
        "isEditable": true,
        "adminLevel": 0
      }
    }
  ]
}

Creates a group.

POST /v2/scim/Groups

Auditing

Calling this method generates the following auditing event.

openpages.group.create

Request

Request Body

Required*

SCIMGroup

Create a group.

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group", "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension" ], "displayName": "group_1007", "members": [ { "value": "1319", "type": "User" } ], "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": { "description": "group_1007", "parentId": "1608", "roleAssignments": [ { "roleName": "BC Manager", "folder": "/_op_sox/Project/Default/BusinessEntity/Test 11" } ] } }'   "{base_url}/v2/scim/Groups"

Response

Response Body

SCIMGroup

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "2110",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
  ],
  "displayName": "group_1007",
  "members": [
    {
      "value": "1319",
      "display": "bfrank",
      "type": "User"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
    "description": "group_1007",
    "isHidden": false,
    "isDeleted": false,
    "isEditable": true,
    "adminLevel": 0,
    "roleAssignments": [
      {
        "roleName": "BC Manager",
        "objectTypeName": "SOXBusEntity",
        "id": "1",
        "role": "510",
        "folder": "/_op_sox/Project/Default/BusinessEntity/Test 11",
        "objectType": "5",
        "securityPrincipal": "2110"
      }
    ],
    "isEnabled": true
  }
}

Gets a Group by the specified ID.

GET /v2/scim/Groups/{id}

Auditing

Calling this method generates the following auditing event.

openpages.group.get

Request

Path Parameters

id
Required*
string
Group name or ID.

Query Parameters

attributes
string
Comma separated list of resource attribute names to be returned in response

Example: attributes=displayName,description
isName
string
If Group name is a numeric value then isName should be true.

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Groups/{id}?attributes=attributes=displayName,description"

Response

Response Body

SCIMGroup

Status Code

200
200 OK
404
Requested object not found

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1622",
  "meta": {
    "resourceType": "Group",
    "location": "https://localhost/opgrc/api/v2/scim/Groups/1622"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
  ],
  "displayName": "Group001",
  "members": [
    {
      "value": "1620",
      "display": "Group002",
      "type": "Group"
    },
    {
      "value": "1621",
      "display": "User001",
      "type": "User"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
    "description": "SCIM test groups",
    "isHidden": false,
    "isDeleted": false,
    "isEditable": true,
    "adminLevel": 0,
    "isEnabled": true
  }
}

Status 404: Object Type not found

404

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "404",
  "detail": "Not Found - OP-05064: The requested group was not found. [VOG1C9S54CJK]"
}

Replaces an existing Group.

PUT /v2/scim/Groups/{id}

Auditing

Calling this method generates the following auditing event.

openpages.group.update

Request

Path Parameters

id
Required*
string
Group name or ID.

Query Parameters

isName
string
If Group name is a numeric value, set isName to true.

Default: false

Request Body

Required*

SCIMGroup

Replace all attributes of an existing group with the request payload

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group", "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension" ], "displayName": "Group 001", "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": { "description": "Group updated for division D001" }, "members": "[]" }'   "{base_url}/v2/scim/Groups/{id}"

Response

Response Body

SCIMGroup

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1635",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
  ],
  "displayName": "Group 001",
  "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
    "description": "Group updated for division D001",
    "isHidden": false,
    "isDeleted": false,
    "isEditable": true,
    "adminLevel": 0,
    "adminPermissions": [],
    "isEnabled": true
  }
}

Patches an existing Group.

PATCH /v2/scim/Groups/{id}

Auditing

Calling this method generates the following auditing event.

openpages.group.update

Request

Path Parameters

id
Required*
string
Group name or ID.

Query Parameters

attributes
string
Comma-separated list of resource attribute names to be returned in response

Example: attributes=displayName,description
isName
string
If Group name is a numeric value then isName should be true.

Default: false

Request Body

Required*

PatchRequest

Update one or more attributes of an existing group. For more details on form of the patch request, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2

Examples:

View

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "Operations": [ { "op": "add", "path": "members", "value": { "value": "1620", "type": "Group" } } ] }'   "{base_url}/v2/scim/Groups/{id}?attributes=attributes=displayName,description"

Response

Response Body

SCIMGroup

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1635",
  "meta": {
    "resourceType": "Group",
    "location": "https://localhost/opgrc/api/v2/scim/Groups/1635"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension"
  ],
  "displayName": "Group 001",
  "members": [
    {
      "value": "1620",
      "display": "Group-cd670aa6-d824-48a6-972c-6af2d56ca3ba",
      "type": "Group"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension": {
    "description": "Group created for division 001",
    "isHidden": false,
    "isDeleted": false,
    "isEditable": true,
    "adminLevel": 0,
    "isEnabled": true
  }
}

Gets all resource types.

GET /v2/scim/ResourceTypes

Auditing

Calling this method generates the following auditing event.

openpages.scim-resource-type.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/ResourceTypes"

Response

Response Body

ListResponse

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "totalResults": 2,
  "itemsPerPage": 10,
  "startIndex": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
      ],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "required": true
        }
      ],
      "meta": {
        "location": "https://example.com/v2/ResourceTypes/User",
        "resourceType": "ResourceType"
      }
    }
  ]
}

Gets a specific resource type by name.

GET /v2/scim/ResourceTypes/{resource_name}

Auditing

Calling this method generates the following auditing event.

openpages.scim-resource-type.get

Request

Path Parameters

resource_name
Required*
string

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/ResourceTypes/{resource_name}"

Response

Response Body

ResourceType

Status Code

200
200 OK
404
Requested Resource type not found

Example responses

Status 200: 200 ok Summary

200

{
  "id": "User",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
  ],
  "name": "User",
  "description": "OpenPages Users",
  "endpoint": "/Users",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:extension:openpages:UserExtension",
      "required": true
    }
  ]
}

Status 404: Resource type not found

404

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "detail": "Bad Request - ResourceType &#39;Employee&#39; is not supported."
}

Gets a schema by the schema URI of the schema definition.

GET /v2/scim/Schemas/{schema_id}

Auditing

Calling this method generates the following auditing event.

openpages.scim-schema.get

Request

Path Parameters

schema_id
Required*
string
Schema URI of Individual schema definitions

Example: urn:ietf:params:scim:schemas:core:2.0:User

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Schemas/{schema_id}"

Response

Response Body

Schema

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Schema"
  ],
  "name": "User",
  "description": "OpenPages Users",
  "attributes": [
    {
      "name": "userName",
      "type": "string",
      "description": "Unique identifier for the User",
      "uniqueness": "NONE"
    },
    {
      "name": "name",
      "type": "complex",
      "multiValued": false,
      "subAttributes": [
        {
          "name": "formatted",
          "type": "string",
          "description": "The full name",
          "required": false,
          "mutability": "READ_WRITE",
          "returned": "DEFAULT"
        },
        {
          "name": "familyName",
          "type": "string",
          "description": "The family name of the User.",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        },
        {
          "name": "givenName",
          "type": "string",
          "description": "The given name of the User.",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        },
        {
          "name": "middleName",
          "type": "string",
          "description": "The middle name(s) of the User.",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        }
      ]
    },
    {
      "name": "displayName",
      "type": "string",
      "description": "The name of the User, suitable for display to end-users.",
      "mutability": "READ_ONLY",
      "returned": "DEFAULT",
      "uniqueness": "NONE"
    }
  ]
}

List SCIM schemas of all resources and extensions.

GET /v2/scim/Schemas

Auditing

Calling this method generates the following auditing event.

openpages.scim-schema.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Schemas"

Response

Response Body

ListResponse

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 4,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
      ],
      "name": "Group",
      "description": "Top level Scim Group",
      "attributes": [
        {
          "name": "displayName",
          "type": "string",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        }
      ]
    },
    {
      "id": "urn:ietf:params:scim:schemas:extension:openpages:GroupExtension",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
      ],
      "name": "Group",
      "description": "Group Schema extension to define OpenPages Group attributes.",
      "attributes": [
        {
          "name": "isEnabled",
          "type": "boolean",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        }
      ]
    },
    {
      "id": "urn:ietf:params:scim:schemas:extension:openpages:UserExtension",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
      ],
      "name": "User",
      "description": "User Schema extension to define OpenPages specific User attributes.",
      "attributes": [
        {
          "name": "passwordCreationDate",
          "type": "dateTime",
          "mutability": "READ_ONLY",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        }
      ]
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
      ],
      "name": "User",
      "description": "OpenPages Users",
      "attributes": [
        {
          "name": "userName",
          "type": "string",
          "mutability": "READ_WRITE",
          "returned": "DEFAULT",
          "uniqueness": "NONE"
        }
      ]
    }
  ]
}

Gets a JSON structure that describes the SCIM specification features available on service provider.

GET /v2/scim/ServiceProviderConfig

Auditing

Calling this method generates the following auditing event.

openpages.scim-service-provider-configuration.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/ServiceProviderConfig"

Response

Response Body

ServiceProviderConfig

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "meta": {
    "resourceType": "ServiceProviderConfig"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
  ],
  "documentationUrl": "",
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false
  },
  "filter": {
    "supported": true,
    "maxResults": 1000
  },
  "changePassword": {
    "supported": true
  },
  "sort": {
    "supported": true
  },
  "etag": {
    "supported": false
  },
  "authenticationSchemes": [
    {
      "type": "HTTP_BASIC",
      "name": "HTTP Basic",
      "description": "Authentication scheme using the HTTP Basic Standard"
    },
    {
      "type": "OAUTH_BEARER",
      "name": "OAuth Bearer Token",
      "description": "Authentication scheme using the OAuth Bearer Token Standard"
    }
  ]
}

Lists the users defined in the OpenPages system. Use filters and response attributes to limit the list of users to return. Specify Pagination and Sort parameters in the Query URL. For filter syntax, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2 . Following attribute operators are supported 'eq', 'ne', 'co', 'sw', 'ew', 'gt', 'ge', 'lt', 'le'. 'pr' is not supported currently. All Logical operators are supported. Query filter can be defined on following user core attributes - 'ID', 'givenName', 'familyName', 'emails', 'userName', 'displayName'. Following user extension attributes can also be used in defining filters - 'description'. Extension attributes MUST be prefixed with extenstion URN when used in filters. Examples:-

filter=userName eq "bjensen"

filter=name.familyName eq "doe" and urn:ietf:params:scim:schemas:extension:openpages:UserExtension:description eq "User created through onboarding module"

To select resource attributes to be returned, use 'attributes' query parameter. For 'attributes' notation, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.5 . This query parameter is a multi-valued list of strings. 'excludedAttributes' is not supported. While listing user extension attributes in the 'attributes' parameter, schema URN can be omitted. Examples :-

attributes=displayName,description

attributes=name.familyName,groups,description,preferredProfileName

To sort the query results, specify 'sortBy' and 'sortOrder' query parameters. In 'sortBy' parameter, the same list of attributes as in query filters are supported. Examples :-

sortBy=userName&sortOrder=descending

sortBy=urn:ietf:params:scim:schemas:extension:openpages:GroupExtension:description&sortOrder=ascending

To page through large number of results, use pagination parameters of 'startIndex' and 'count'. refer https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4

GET /v2/scim/Users

Auditing

Calling this method generates the following auditing event.

openpages.user.list

Request

Query Parameters

filter
string
Filter string used to request a subset of resources

Example: filter=userName eq "bjensen"
attributes
string
Comma separated list of resource attribute names to be returned in response

Default:
Example: attributes=name,groups,description,preferredProfileName
sortOrder
string
Specifies sort order. Values are 'ascending' or 'descending'

Default: ascending
sortBy
string
Resource attribute name to sort on.
startIndex
int32
1-based index of the first query result

Default: 1
count
int32
Specifies the desired maximum number of results per page

Default: 100

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Users?filter=filter=userName eq \"bjensen\"&attributes=attributes=name,groups,description,preferredProfileName"

Response

Response Body

SCIMUser

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "id": "609",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
      ],
      "userName": "alaudit",
      "name": {
        "familyName": "Audit",
        "givenName": "Al"
      },
      "displayName": "Al Audit - alaudit@localhost.com - alaudit",
      "locale": "en_US",
      "active": true,
      "emails": [
        {
          "value": "alaudit@localhost.com"
        }
      ],
      "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
        "isLocked": false,
        "isHidden": false,
        "isDeleted": false,
        "isEditable": true,
        "adminLevel": 0,
        "passwordCreationDate": "2023-04-28T03:06:46.216-04:00",
        "passwordExpiresInDays": 0,
        "canChangePassword": true,
        "isPasswordChangeFromAdmin": false,
        "isSecurityAdministrator": false
      }
    },
    {
      "id": "610",
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
      ],
      "userName": "annaudit",
      "name": {
        "familyName": "Audit",
        "givenName": "Ann"
      },
      "displayName": "Ann Audit - annaudit@localhost.com - annaudit",
      "locale": "en_US",
      "active": true,
      "emails": [
        {
          "value": "annaudit@localhost.com"
        }
      ],
      "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
        "isLocked": false,
        "isHidden": false,
        "isDeleted": false,
        "isEditable": true,
        "adminLevel": 0,
        "passwordCreationDate": "2023-04-28T03:06:46.416-04:00",
        "passwordExpiresInDays": 0,
        "canChangePassword": true,
        "isPasswordChangeFromAdmin": false,
        "isSecurityAdministrator": false
      }
    }
  ]
}

Creates a user.

POST /v2/scim/Users

Auditing

Calling this method generates the following auditing event.

openpages.user.create

Request

Request Body

Required*

SCIMUser

Creates a user.

Examples:

View

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:openpages:UserExtension" ], "userName": "user001", "name": { "familyName": "John", "givenName": "Doe" }, "emails": [ { "value": "johndoe@test.com" } ], "password": "something", "locale": "en_US", "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": { "description": "created through scim api" } }'   "{base_url}/v2/scim/Users"

Response

Response Body

SCIMUser

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1636",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
  ],
  "userName": "user001",
  "name": {
    "familyName": "John",
    "givenName": "Doe"
  },
  "displayName": "Doe John - johndoe@test.com - user001",
  "locale": "en_US",
  "active": true,
  "emails": [
    {
      "value": "johndoe@test.com"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
    "description": "created through scim api",
    "isSecurityAdministrator": false,
    "preferredProfileName": "Testing"
  }
}

Gets a user by ID or userName.

GET /v2/scim/Users/{id}

Auditing

Calling this method generates the following auditing event.

openpages.user.get

Request

Path Parameters

id
Required*
string
User name or ID.

Query Parameters

isName
string
If User name is a numeric value then isName should be true.

Default: false
attributes
string
Comma separated list of resource attribute names to be returned in response

Example: attributes=name,groups,description,preferredProfileName

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/scim/Users/{id}?attributes=attributes=name,groups,description,preferredProfileName"

Response

Response Body

SCIMUser

Status Code

200
200 OK
404
Requested object not found

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1311",
  "meta": {
    "resourceType": "User",
    "location": "https://localhost/opgrc/api/v2/scim/Users/1311"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
  ],
  "userName": "aburr",
  "name": {
    "familyName": "Burr",
    "givenName": "Aaron"
  },
  "displayName": "Aaron Burr - aaron.burr@test.com - aburr",
  "locale": "en_US",
  "active": true,
  "emails": [
    {
      "value": "aaron.burr@test.com"
    }
  ],
  "groups": [
    {
      "value": "3",
      "display": "OpenPages",
      "type": "Group"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
    "description": "Aaron Burr user from division 1",
    "isLocked": false,
    "isHidden": false,
    "isDeleted": false,
    "isEditable": true,
    "adminLevel": 0,
    "roleAssignments": [
      {
        "roleName": "DevApiCreateIssue",
        "objectTypeName": "SOXBusEntity",
        "id": "1",
        "role": "1294",
        "folder": "/_op_sox/Project/Default/BusinessEntity/Test 11",
        "objectType": "5",
        "securityPrincipal": "1311"
      }
    ],
    "passwordCreationDate": "2023-03-17T04:14:02.721-04:00",
    "passwordExpiresInDays": 0,
    "canChangePassword": true,
    "isPasswordChangeFromAdmin": false,
    "isSecurityAdministrator": false,
    "availableProfileNames": [
      "Testing"
    ],
    "preferredProfileName": "Testing"
  }
}

Status 404: Object Type not found

404

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "404",
  "detail": "Not Found - OP-05062: The requested user was not found. [VOGZG0WWWBY0]"
}

Replace an existing user with the user request.

PUT /v2/scim/Users/{id}

Auditing

Calling this method generates the following auditing event.

openpages.user.update

Request

Path Parameters

id
Required*
string
User name or ID.

Query Parameters

isName
string
If User name is a numeric value then isName should be true.

Default: false

Request Body

Required*

SCIMUser

Replace all attributes of an existing user with the request payload

Examples:

View

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:openpages:UserExtension" ], "userName": "user001", "name": { "familyName": "Johnn", "givenName": "Doe" }, "emails": [ { "value": "johnndoe2@test.com" } ], "password": "passw0rd", "locale": "en_US", "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": { "description": "Updated through scim api" } }'   "{base_url}/v2/scim/Users/{id}"

Response

Response Body

SCIMUser

Status Code

200
200 OK

Example responses

Status 200: 200 ok Summary

200

{
  "id": "1636",
  "meta": {
    "resourceType": "User",
    "location": "https://localhost/opgrc/api/v2/scim/Users/1636"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
  ],
  "userName": "user001",
  "name": {
    "familyName": "Johnn",
    "givenName": "Doe"
  },
  "displayName": "Doe Johnn - johnndoe@test.com - user001",
  "locale": "en_US",
  "active": true,
  "emails": [
    {
      "value": "johnndoe@test.com"
    }
  ],
  "groups": [
    {
      "value": "3",
      "display": "OpenPages",
      "type": "Group"
    },
    {
      "value": "4",
      "display": "Standalone Users and Groups",
      "type": "Group"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
    "description": "Updated through scim api",
    "isSecurityAdministrator": false,
    "preferredProfileName": "Testing"
  }
}

Updates the attributes of an existing user. For more details on the format of the patch request, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2

PATCH /v2/scim/Users/{id}

Auditing

Calling this method generates the following auditing event.

openpages.user.update

Request

Path Parameters

id
Required*
string
User name or ID

Query Parameters

isName
string
If User name is a numeric value then isName should be true.

Default: false
attributes
string
Comma separated list of resource attribute names to be returned in response

Example: attributes=name,groups,description,preferredProfileName

Request Body

Required*

PatchRequest

Patches an existing user

Examples:

View

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "Operations": [ { "op": "replace", "path": "name", "value": { "familyName": "New_familyName", "givenName": "NewGivenName" } } ] }'   "{base_url}/v2/scim/Users/{id}?attributes=attributes=name,groups,description,preferredProfileName"

Response

Status Code

default
200

Example responses

Status default: 200 ok Summary

200

{
  "id": "1636",
  "meta": {
    "resourceType": "User",
    "location": "https://localhost/opgrc/api/v2/scim/Users/1636"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:openpages:UserExtension"
  ],
  "userName": "user001",
  "name": {
    "familyName": "New_familyName",
    "givenName": "NewGivenName"
  },
  "displayName": "NewGivenName New_familyName - johnndoe@test.com - user001",
  "locale": "en_US",
  "active": true,
  "emails": [
    {
      "value": "johnndoe@test.com"
    }
  ],
  "groups": [
    {
      "value": "3",
      "display": "OpenPages",
      "type": "Group"
    },
    {
      "value": "4",
      "display": "Standalone Users and Groups",
      "type": "Group"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:openpages:UserExtension": {
    "description": "created through scim api",
    "isSecurityAdministrator": false
  }
}

Retrieve workflow instance data for the given workflow instance id.

GET /v2/workflows/instances/{id}

Auditing

Calling this method generates the following auditing event.

openpages.workflow-resource.get

Request

Path Parameters

id
Required*
string
The Activity Instance id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/instances/{id}"

Response

Response Body

workflow_activity_instance_data_type

The workflow activity instance data type definition.

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "id": "385",
  "status": "Stage 2",
  "criticality": "medium",
  "due_date": "5/29/2013",
  "assignees": [
    "pcm"
  ],
  "process_start_date": "6/14/2023",
  "process_due_date": "6/5/2013",
  "grc_object": {
    "id": "9001",
    "name": "Iss-11-001-AI_03",
    "path": "/_op_sox/Project/Default/IssueActionItems/Global Financial Services/North America/Retail Banking",
    "type_definition": {
      "id": "7",
      "name": "SOXTask",
      "label": "Action Item"
    }
  },
  "workflow": {
    "id": "1",
    "name": "Action Item Approval Workflow",
    "label": "Action Item Approval Workflow",
    "version": "1",
    "activity": {
      "id": "3",
      "name": "Stage 2",
      "label": "In Progress"
    }
  }
}

Returns a workflow process definition given it's id.

GET /v2/workflows/definitions/{id}

Auditing

Calling this method generates the following auditing event.

openpages.workflow.get

Request

Path Parameters

id
Required*
string
The Workflow definition id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/definitions/{id}"

Response

Response Body

workflow_definition_type

The workflow definition

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "Sample Workflow",
  "label": "Sample Workflow",
  "modifiedDate": "2026-07-05T02:42:59.042-04:00",
  "modifiedBy": "admin",
  "createdDate": "2026-07-05T02:42:59.042-04:00",
  "createdBy": "admin",
  "id": "36",
  "version_id": "36",
  "type": "standard",
  "type_definition_name": "SOXBusEntity",
  "version_number": "1",
  "latest_version_number": "1",
  "state": "published",
  "last_version_state": "published",
  "is_automated": false,
  "is_enabled": true,
  "activities": [
    {
      "name": "Start",
      "label": "Start",
      "transitions": [
        {
          "name": "Complete",
          "label": "Complete",
          "target": "End",
          "run_in_background": false,
          "notify_assignees": true,
          "notify_subscribers": true
        }
      ],
      "id": "151",
      "type": "start",
      "access_type": "open"
    },
    {
      "name": "End",
      "label": "End",
      "id": "152",
      "type": "end",
      "access_type": "open"
    }
  ]
}

Returns a workflow process definition given it's versionid.

GET /v2/workflows/definitions/version/{id}

Auditing

Calling this method generates the following auditing event.

openpages.workflow-version.get

Request

Path Parameters

id
Required*
string
The Workflow definition version id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/definitions/version/{id}"

Response

Response Body

workflow_definition_type

The workflow definition

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "name": "Sample Workflow",
  "label": "Sample Workflow",
  "modifiedDate": "2026-07-05T02:42:59.042-04:00",
  "modifiedBy": "admin",
  "createdDate": "2026-07-05T02:42:59.042-04:00",
  "createdBy": "admin",
  "id": "36",
  "version_id": "36",
  "type": "standard",
  "type_definition_name": "SOXBusEntity",
  "version_number": "1",
  "latest_version_number": "2",
  "state": "published",
  "last_version_state": "draft",
  "is_automated": false,
  "is_enabled": true,
  "activities": [
    {
      "name": "Start",
      "label": "Start",
      "transitions": [
        {
          "name": "Complete",
          "label": "Complete",
          "target": "End",
          "run_in_background": false,
          "notify_assignees": true,
          "notify_subscribers": true
        }
      ],
      "id": "151",
      "type": "start",
      "access_type": "open"
    },
    {
      "name": "End",
      "label": "End",
      "id": "152",
      "type": "end",
      "access_type": "open"
    }
  ]
}

Returns all workflow process definitions. Use optional parameter to filter by object type.

GET /v2/workflows/definitions

Auditing

Calling this method generates the following auditing event.

openpages.workflow.list

Request

Query Parameters

object_type
string
The GRC object type to return workflows for. Can be an id or a name.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
include_activities
string
Activities and actions are included by default. Set this to false to filter them out.

Possible values: 1 ≤ length ≤ 5, Value must match regular expression [A-Za-z]*
Default: true

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/definitions"

Response

Response Body

WFProcessDefinitionTypes

Collection of WFProcessDefinitionType Objects

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "definitions": [
    {
      "name": "Sample Workflow",
      "label": "Sample Workflow",
      "modifiedDate": "2026-07-05T02:42:59.042-04:00",
      "modifiedBy": "admin",
      "createdDate": "2026-07-05T02:42:59.042-04:00",
      "createdBy": "admin",
      "id": "36",
      "version_id": "36",
      "type": "standard",
      "type_definition_name": "SOXBusEntity",
      "version_number": "1",
      "latest_version_number": "1",
      "state": "published",
      "last_version_state": "published",
      "is_automated": false,
      "is_enabled": true,
      "activities": [
        {
          "name": "Start",
          "label": "Start",
          "transitions": [
            {
              "name": "Complete",
              "label": "Complete",
              "target": "End",
              "run_in_background": false,
              "notify_assignees": true,
              "notify_subscribers": true
            }
          ],
          "id": "151",
          "type": "start",
          "access_type": "open"
        },
        {
          "name": "End",
          "label": "End",
          "id": "152",
          "type": "end",
          "access_type": "open"
        }
      ]
    }
  ]
}

Transitions grc object to the new workflow state based on the instance id and transition name.

POST /v2/workflows/instances/{id}/transition/{transition}

Auditing

Calling this method generates the following auditing event.

openpages.workflow-resource.commit

Request

Path Parameters

id
Required*
string
The Workflow instance id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*
transition
Required*
string
The name of the Workflow action to perform.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [A-Za-z]*

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/instances/{id}/transition/{transition}"

Response

Status Code

200
Successfully ran the workflow on the grc object, transitioning the grc object to the new state.

Example responses

Status 200: 200 ok Summary

200

{
  "grc_object_id": "13002",
  "workflow_id": "121",
  "process_state": "open",
  "activity_instance_id": "741",
  "activity_id": "582",
  "activity_name": "processing_stage",
  "activity_label": "processing_stage"
}

Returns all workflow process instance data based on the search parameter.

GET /v2/workflows/instances/search

Auditing

Calling this method generates the following auditing event.

openpages.workflow-resource.search

Request

Query Parameters

sort_field
string
Field to sort results by.

Allowable values: [due_date,workflow,activity]
Default: due_date
sort_direction
string
Direction to sort results. asc or desc

Allowable values: [asc,desc]
Default: asc
user_role
string
User's role to filter on.

Allowable values: [assignee,subscriber,oversight]
user
string
User to filter on. Can be username or id.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
type_definition
string
Type Definition to filter on. Can be name or id.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
workflow
string
Workflow to filter on. Can be name or id.

Possible values: 1 ≤ length ≤ 1024, Value must match regular expression [A-Za-z0-9]+(,[A-Za-z0-9]+)*
include_counts
string
Whether to return due date result counts with the list of activity instances

Default: false
group_dimension
string
Dimension to group due date counts by.

Allowable values: [type_definition,criticality,workflow,activity]
Default: type_definition
date_interval
string
The scope to aggregate due date counts.

Allowable values: [day,week,month,year]
Default: week
offset
string
The page of results to return.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*
Default: 1
limit
string
The max number of results returned by each request.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/instances/search"

Response

Response Body

WFActivityInstanceSearchResultType

Status Code

200
200

Example responses

Status 200: 200 ok Summary

200

{
  "activity_instances": [
    {
      "id": "3",
      "status": "Stage 2",
      "criticality": "medium",
      "due_date": "9/8/2013",
      "assignees": [
        "OpenPagesAdministrator"
      ],
      "process_start_date": "6/14/2023",
      "process_due_date": "9/15/2013",
      "grc_object": {
        "id": "9004",
        "name": "Iss-11-001-AI_06",
        "path": "/_op_sox/Project/Default/ICDocumentation/Workpapers/AI/001",
        "type_definition": {
          "id": "7",
          "name": "SOXTask",
          "label": "Action Item"
        }
      },
      "workflow": {
        "id": "388",
        "name": "Action Item Approval Workflow",
        "label": "Action Item Approval Workflow",
        "version": "1",
        "activity": {
          "id": "1",
          "name": "In Progress",
          "label": "In Progress"
        }
      }
    }
  ],
  "paging": {
    "total_count": 212,
    "page": 1,
    "page_size": 40
  }
}

Start the workflow process for the given workflow id and grc object id.

POST /v2/workflows/definitions/{id}/start/{grc_object_id}

Auditing

Calling this method generates the following auditing event.

openpages.workflow-resource.start

Request

Path Parameters

id
Required*
string
The Workflow definition id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*
grc_object_id
Required*
string
The Grc Object id.

Possible values: 1 ≤ length ≤ 10, Value must match regular expression [0-9]*

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/workflows/definitions/{id}/start/{grc_object_id}"

Response

Status Code

200
Workflow process started successfully for the given grc object id.

Example responses

Status 200: 200 ok Summary

200

{
  "grc_object_id": "13002",
  "workflow_id": "121",
  "activity_instance_id": "741",
  "activity_id": "582",
  "activity_name": "processing_stage",
  "activity_label": "processing_stage"
}

Introduction

Endpoint URIs

Support for SCIM

Authentication

Security scheme

bearerToken

Attribute

Type

Scheme

Bearer format

basicAuth

Attribute

Type

Scheme

Auditing

Error handling

Pagination

Methods

Get Tags

Auditing

Request

Query Parameters

only_enabled

Response

Response Body

tags

Status Code

200

Add Tags

Auditing

Request

Request Body

tags

Response

Response Body

tags

Status Code

201

400

Decrypt using External Key

Auditing

Request

No Request Parameters

Response

Response Body

response

Status Code

200

Encrypt using External Key

Auditing

Request

No Request Parameters

Response

Response Body

response

Status Code

200

Get Base Currency

Auditing

Request

No Request Parameters

Response

Response Body

iso_code

name

symbol

id

precision

is_base_currency

is_enabled

Status Code

200

Get Child Settings

Auditing

Request

Path Parameters

setting_path

Query Parameters

offset

limit