Get an Questionnaire Type by ID
GET /v2/questionnaire/{id}/assessment
Gets a Assesment. Use optional parameters to control what data is returned.
Auditing
Calling this method generates the following auditing event.
openpages.object-type.get
Request
Path Parameters
id
Required *
string
Query Parameters
Response
200 - 200 OK
weight
integer
compliance_score
number
risk_score
number
title
string
Title of the questionnaire or section
name
string
Name of the questionnaire or section
sections
array
Collection of sections
404 - Object Type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get an Questionnaire Type by ID
GET /v2/questionnaire/{id}/template
Gets a Questionnaire. Use optional parameters to control what data is returned.
Auditing
Calling this method generates the following auditing event.
openpages.object-type.get
Request
Path Parameters
id
Required *
string
Query Parameters
Response
200 - 200 OK
id
string
Unique identifier for the resource
order
integer
Order of the item, defaults to -1 if not set
title
string
Title of the questionnaire or section
description
string
Description of the questionnaire or section
enable_titles
boolean
Flag indicating whether titles are enabled
enable_auto_numbering
boolean
Flag indicating whether auto-numbering is enabled
enable_weight_score
boolean
enable_weight_score
required
boolean
Flag indicating whether the questionnaire is required
questionnaire_depth
integer
Depth of the questionnaire (how many levels it has)
version
string
Version of the questionnaire
sections
array
Collection of sections
questions
array
Collection of questions
comments
array
Collection of localized guidance
attachments
array
Collection of attachments
response_actions
array
Collection of response actions
dependencies
array
Collection of question dependencies
completion_required
boolean
Indicates if completion is required
owner
string
The owner of the resource
status
string
The current status of the resource
review_mode
boolean
Indicates if the resource is in review mode
read_only
boolean
Indicates if the resource is in read-only mode
last_modified_date
integer
The last modified date of the resource
actions
array
List of actions associated with the resource
action_labels
array
List of labels for the actions
action_type
string
The type of action to be performed
associated_template_name
string
Name of the associated template
recalc_score
boolean
Indicates if the score should be recalculated
rationale
string
Rationale behind the questionnaire or section
reference
string
Reference for the questionnaire or section
report_id
string
Report ID associated with the questionnaire
operation
string
Operation associated with the questionnaire
due_date
integer
The due date for the resource
action
string
The action to be performed
can_read_resource
boolean
Indicates if the resource can be read
can_update_resource
boolean
Indicates if the resource can be updated
can_process_transition
boolean
Indicates if the resource can process transitions
missing_attachments_error
boolean
Missing attachments error
404 - Object Type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Decrypt using External Key
PUT /v2/configuration/decrypt_with_external_key
Decrypts all data, such as OpenPages storage and sensitive information in OpenPages database, using an external key.
Auditing
Calling this method generates the following auditing event.
openpages.configuration-encryption.set-off
Request
Response
200 - 200
response
string
REST response field
Encrypt using External Key
PUT /v2/configuration/encrypt_with_external_key
Encrypts all data, such as OpenPages storage and sensitive information in OpenPages database, using an external key.
Auditing
Calling this method generates the following auditing event.
openpages.configuration-encryption.set-on
Request
Response
200 - 200
response
string
REST response field
Get Base Currency
GET /v2/configuration/currencies/base
Gets the Base Currency information for this system. The Base Currency is typically set at install time.
Auditing
Calling this method generates the following auditing event.
openpages.base-currency.list
Request
Response
200 - 200
iso_code
string
Currency ISO Code
name
string
Currency name
symbol
string
Currency symbol
precision
integer
Currency precision
is_base_currency
boolean
Is Base Currency
is_enabled
boolean
Is Currency enabled
id
string
Currency ID
Get Child Settings
GET /v2/configuration/settings/all/{setting_path}
Gets values for all child configurations in the specified 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.
Query Parameters
offset
integer
0-based index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
settings
array
Collection of Setting Types
Get Currencies
GET /v2/configuration/currencies
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.
Auditing
Calling this method generates the following auditing event.
openpages.currency.list
Request
Path Parameters
Query Parameters
only_enabled
boolean
If set to true, returns only enabled currencies. Default is false.
Response
200 - 200
currencies
array
Collection of Currency Types
Get Currency by ISO code
GET /v2/configuration/currencies/{code}
Gets the details about a Currency by specifying an ISO code.
Auditing
Calling this method generates the following auditing event.
openpages.currency.get
Request
Path Parameters
code
Required *
string
ISO currency code.
Query Parameters
Response
200 - 200
iso_code
string
Currency ISO Code
name
string
Currency name
symbol
string
Currency symbol
precision
integer
Currency precision
is_base_currency
boolean
Is Base Currency
is_enabled
boolean
Is Currency enabled
id
string
Currency ID
Set Currency status
PUT /v2/configuration/currencies/{code}
Sets the status of a Currency to be enabled or disabled.
Auditing
Calling this method generates the following auditing event.
openpages.currency.update
Request
Path Parameters
code
Required *
string
ISO currency code.
Query Parameters
enable
Required *
boolean
Status to set on the Currency.
Response
202 - Set Currency status successfully.
Get Current Reporting Period
GET /v2/configuration/reporting_periods/current
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.
Auditing
Calling this method generates the following auditing event.
openpages.current-reporting-period.get
Request
Response
200 - 200
id
string
Reporting Period ID
label
string
Reporting Period label
description
string
Reporting Period description
finalized_date
string
Reporting Period finalized date
creation_date
string
Reporting Period creation date
modified_date
string
Reporting Period modified date
Get exchange rates for a Currency
GET /v2/configuration/currencies/{code}/exchange_rates
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.
Auditing
Calling this method generates the following auditing event.
openpages.currency-history.list
Request
Path Parameters
code
Required *
string
ISO currency code.
Query Parameters
date
string
The date for which to retrieve the exchange rate. The expected date format is ISO 8601 'yyyyMMdd'T'HHmmss'Z''
history
boolean
Return all the historical exchange rates for the Currency if the date is not specified.
offset
integer
0-based index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
exchange_rates
array
Collection of Exchange Rate Types
Sets exchange rate for Currency
POST /v2/configuration/currencies/{code}/exchange_rates
Sets an exchange rate for a Currency.
Auditing
Calling this method generates the following auditing event.
openpages.currency.update
Request
Request Body
ExchangeRateType
Exchange rate to set.
id
string
Exchange rate ID
currency_code
string
Currency code
rate
number
Exchange rate
start_date
string
Start date
end_date
string
End date
Path Parameters
code
Required *
string
ISO currency code.
Query Parameters
Response
204 - Exchange rate set successfully. No Content.
Get Locales
GET /v2/configuration/locales
Gets a list of locales supported by OpenPages.
Auditing
Calling this method generates the following auditing event.
openpages.tag.update
Request
Path Parameters
Query Parameters
enabled
boolean
If set to true, returns only enabled locales. If set to false, returns both enabled and disabled locales. Default is true.
created
boolean
If set to true, returns only locales that have been successfully created. When a user adds a new locale, the creation of the locale doesn't happen instantly. A locale in the process of being created is disabled, and is not returned when the 'created' parameter is set to true. Default is true.
Response
200 - List of locales
locales
array
Collection of Locale Types
Get Localized Application Text
GET /v2/configuration/text/{text_key}
Gets the Localized Application Text label for the current user's locale.
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".
Query Parameters
Response
200 - 200
response
string
REST response field
Get All Application Text
GET /v2/configuration/text
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.
Auditing
Calling this method generates the following auditing event.
openpages.application-text.list
Request
Path Parameters
Query Parameters
include_localized_labels
boolean
Include localized labels for all locales.
category_filters
string
Comma-separated category name to filter application texts.
offset
integer
0-based index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
text
array
Collection of application text
Get Profile by ID
GET /v2/configuration/profiles/{profile}
Gets a Profile summary.
Auditing
Calling this method generates the following auditing event.
openpages.profile.get
Request
Path Parameters
profile
Required *
string
Profile name or ID.
Query Parameters
Response
200 - 200
id
string
Profile type ID
name
string
Profile type name
description
string
Profile type description
is_default
boolean
Is default Profile type
is_fallback
boolean
Is fallback Profile type
is_enabled
boolean
Is Profile type enabled
is_deleted
boolean
Is Profile type deleted
Get Profile Definition
GET /v2/configuration/profiles/{profile}/definition
Gets a full profile definition including object types, fields, and views.
Auditing
Calling this method generates the following auditing event.
openpages.profile.get
Request
Path Parameters
profile
Required *
string
Profile name or ID.
Query Parameters
Response
200 - 200
id
string
Profile type ID
name
string
Profile type name
description
string
Profile type description
is_default
boolean
Is default Profile type
is_fallback
boolean
Is fallback Profile type
is_enabled
boolean
Is Profile type enabled
is_deleted
boolean
Is Profile type deleted
Get Profile Fields
GET /v2/configuration/profiles/fields
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.
Auditing
Calling this method generates the following auditing event.
openpages.profile-object-field.list
Request
Path Parameters
Query Parameters
profile
Required *
string
Profile name
type
Required *
string
Object Type system name
Response
200 - 200
fields
array
Collection of Profile field definition types
Get Profiles
GET /v2/configuration/profiles
Gets a list of all Profiles summary information.
Auditing
Calling this method generates the following auditing event.
openpages.profile.list
Request
Response
200 - 200
profiles
array
Collection of Profile Types
Get Reporting Period by Name
GET /v2/configuration/reporting_periods/{reporting_period}
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.
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.
Query Parameters
Response
200 - 200
id
string
Reporting Period ID
label
string
Reporting Period label
description
string
Reporting Period description
finalized_date
string
Reporting Period finalized date
creation_date
string
Reporting Period creation date
modified_date
string
Reporting Period modified date
Get All Reporting Periods
GET /v2/configuration/reporting_periods
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.
Auditing
Calling this method generates the following auditing event.
openpages.reporting-period.list
Request
Response
200 - 200
reporting_periods
array
Collection of ReportingPeriod Types
Get Setting
GET /v2/configuration/settings/{setting_path}
Gets the value of the configuration setting by the specified 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.
Query Parameters
Response
200 - 200
key
string
Setting key
value
string
Setting value
Get System Admin Mode
GET /v2/configuration/admin_mode
Gets the status of System Admin Mode. The status can be either true, meaning that System Admin Mode is enabled, or false.
Auditing
Calling this method generates the following auditing event.
openpages.system-admin-mode.get
Request
Response
200 - 200
response
string
REST response field
Set System Admin Mode
PUT /v2/configuration/admin_mode
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.
Auditing
Calling this method generates the following auditing event.
openpages.system-admin-mode.update
Request
Path Parameters
Query Parameters
enable
Required *
boolean
Set true to enable System Admin Mode , or false to disable.
Response
202 - Set System Admin Mode successfully.
Get Tag
GET /v2/configuration/tags/{tagid}
Gets the details about the tag identified by the specified tag_id.
Auditing
Calling this method generates the following auditing event.
openpages.tag.get
Request
Path Parameters
tagid
Required *
string
Tag ID.
Query Parameters
Response
200 - 200
tag_id
string
Tag ID
name
string
Tag Name
description
string
Tag description
enabled
string
Is Tag enabled
created_on
string
Date Tag was created on
created_by
string
User who created the Tag
modified_date
string
Tag modified date
last_modified_by
string
Author of latest tag modification
Update Tag
PUT /v2/configuration/tags/{tagid}
Updates an existing Tag.
Auditing
Calling this method generates the following auditing event.
openpages.tag.update
Request
Request Body
tag_type
Tag Type to update
tag_id
string
Tag ID
name
string
Tag Name
description
string
Tag description
enabled
Required *
string
Is Tag enabled
created_on
string
Date Tag was created on
created_by
string
User who created the Tag
modified_date
string
Tag modified date
last_modified_by
string
Author of latest tag modification
Path Parameters
tagid
Required *
string
Tag ID
Query Parameters
Response
200 - Tag updated
tag_id
string
Tag ID
name
string
Tag Name
description
string
Tag description
enabled
string
Is Tag enabled
created_on
string
Date Tag was created on
created_by
string
User who created the Tag
modified_date
string
Tag modified date
last_modified_by
string
Author of latest tag modification
Integrate Cognos Service
PUT /v2/configuration/integrate_cognos_service
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.
Auditing
Calling this method generates the following auditing event.
openpages.cognos.configure
Request
Response
202 - Integration with Cognos successful.
Set Multiple Exchange Rates
POST /v2/configuration/currencies/exchange_rates
Sets Currency exchange rates with a list of exchange rates for multiple currencies.
Auditing
Calling this method generates the following auditing event.
openpages.currency-list.update
Request
Request Body
ExchangeRateTypes
List of exchange rates to set for multiple currencies
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
exchange_rates
Required *
array
Collection of Exchange Rate Types
Response
204 - Set multiple exchange rates successfully. No Content.
Update Setting Value
PUT /v2/configuration/settings
Updates the value of the configuration setting specified by the path.
Auditing
Calling this method generates the following auditing event.
openpages.setting.get
Request
Request Body
The path that specifies the setting and the key-value pair that specifies the value to update. An example of a path: `/OpenPages/Applications/GRCM/Audit Trail/Show Audit Trail For Custom Forms`. Because the path contains slashes (/), it must be URL-encoded.
Response
200 - 200
key
string
Setting key
value
string
Setting value
Enable or Disable Trace Log Options
PUT /v2/configuration/traces
Enables or disables Trace Log options.
Auditing
Calling this method generates the following auditing event.
openpages.trace-options.update
Request
Request Body
TraceLogListType
Trace Log options to set
trace_list
Required *
array
Collection of Trace Log Types
Response
202 - Trace Log options were enabled or disabled successfully.
Add Child Associations
POST /v2/contents/{id}/associations/children
Adds child associations from one GRC Object to other GRC Objects. Locked parent cannot be associated, except when allowed by registry setting:/OpenPages/Applications/GRCM/Locked Objects/Allowed Associations/*
Auditing
Calling this method generates the following auditing event.
openpages.resource.add
Request
Request Body
AssociationNodeTypes
List of child associations to create
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
associations
Required *
array
Collection of Association Nodes
Path Parameters
id
Required *
string
The GRC Object ID or path. This path can be either a relative path or a full path.
Query Parameters
Response
202 - Accepted request to create child associations
400 - Association ID cannot be null.
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Remove Children Associations
DELETE /v2/contents/{id}/associations/children
Removes child associations from one GRC Object to other GRC Objects.
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.
Query Parameters
children
string
Comma-delimited list of child IDs
Response
204 - Object child associations deleted successfully. No Content.
Add Parent Associations
POST /v2/contents/{id}/associations/parents
Adds parent associations from one GRC Object to other GRC Objects. Association can only occur if the child is unlocked. If the parent is locked, the association is permitted only if allowed by the registry setting:/OpenPages/Applications/GRCM/Locked Objects/Allowed Associations/*
Auditing
Calling this method generates the following auditing event.
openpages.resource.add
Request
Request Body
AssociationNodeTypes
List of parent associations to create
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
associations
Required *
array
Collection of Association Nodes
Path Parameters
id
Required *
string
The GRC Object ID or path. This path can be either a relative path or a full path.
Query Parameters
Response
202 - Accepted request to create parent associations
400 - Association ID cannot be null.
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Remove Parent Associations
DELETE /v2/contents/{id}/associations/parents
Removes parent associations from one GRC Object to other GRC Objects.
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.
Query Parameters
parents
string
Comma-delimited list of parent IDs
Response
204 - Object parent associations deleted successfully. No Content.
Disassociate Tags
DELETE /v2/contents/{id}/tags
Disassociates one or more Tags from a GRC Object.
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.
Query Parameters
tag_ids
string
Comma-delimited list of Tag IDs
Response
204 - Tags disassociated successfully. No Content.
Get Object Types a User Can Create
GET /v2/contents/permissions/allowedtocreatetypes
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-permission.get
Request
Path Parameters
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.
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.
Response
200 - 200 OK
allowedtocreatetypes
array
List of allowed Object types to create
Get Child Object Types that the User can Create for a Specified Parent
GET /v2/contents/{id}/permissions/allowedtocreatetypes
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-permission.get
Request
Path Parameters
id
Required *
string
GRC Object ID or path.
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.
Response
200 - 200 OK
allowedtocreatetypes
array
List of allowed Object types to create
Get GRC Object Associations
GET /v2/contents/{id}/associations
Gets a list of all GRC Object associations to other GRC Objects.
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
Query Parameters
association_type
string
Filters object associations based on association type. Value can be parent or child.
offset
integer
0-based index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
associations
array
Collection of Association Nodes
Add Associations
POST /v2/contents/{id}/associations
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.add
Request
Request Body
AssociationNodeTypes
Request body that includes the list of associations to create
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
associations
Required *
array
Collection of Association Nodes
Path Parameters
id
Required *
string
The GRC Object ID or path. This path can be either a relative path or a full path.
Query Parameters
Response
204 - 204. No Content.
400 - Association ID cannot be null.
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Remove Associations
DELETE /v2/contents/{id}/associations
Removes the associations from one GRC Object to other GRC Objects.
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.
Query Parameters
parents
string
Comma-delimited list of parent IDs
children
string
Comma-delimited list of child IDs
Response
204 - Object associations deleted successfully. No Content.
Copy GRC Objects
PUT /v2/contents/{id}/action/copy
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-copy.commit
Request
Request Body
ActionType
Request body containing the list of Object IDs to be copied and options for the copy action.
ids
Required *
array
Collection of Object IDs
options
Required *
OptionType
Defines Action Option Type
include_children
boolean
Flag to include Children Objects in the action or not
conflict_behavior
Required *
string
Specifies the desired behavior when a GRCObject with the same name already exists in the target location
type_definitions
Required *
array
type_definitions
type_associations
Required *
array
Specifies the list of object type associations that need to be honored during the Action
auto_name_children
boolean
Flag to specify if the associated children of the source GRCObject should be autoNamed or not when copied.
Path Parameters
id
Required *
string
Parent GRC Object ID or Path to copy the other objects to.
Query Parameters
Response
200 - 200
grcobjects
array
Collection of GrcObjects
POST /v2/contents/bulk
Create list of new GRC Object instances. It can also create Document types with attachment content. The IDs used for each type definitions and file types are available in the /types API.Already existing objects in will get updated. Maximum objects created in a request is 100. Partial success will return successful results with 206 status code.
- `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. To convert PDF document to base64, save the pdf file(MyTestPdf.pdf) in a folder. Depending on your operating system, you can use a tool to convert a file to base64. For example on Mac OSX or Linux, open terminal in that folder and use base64 command base64 -i MyTestPdf.pdf > pdfToBase64 Open the new file(pdfToBase64), copy the contents and set it in the `content_definition.children` attribute. Query parameter'proceed_on_error' is true by default which alows to process contents and skip failures. If this flag is passed as false, processing will stop on first point of failure and return the partial content. `not_processed_grc_object_names` list of grc objects not processed. `failed_grc_object_name` grc object which caused failure.
Auditing
Calling this method generates the following auditing event.
openpages.resource.createBulk
Request
Request Body
DocumentCreateObjects
Creates list of GRC objects.
create_objects
Required *
array
Collection of Document create objects
Path Parameters
Query Parameters
append_enum_vals
boolean
Flag to create enum if it doesn't exist
proceed_on_error
boolean
Flag to proceed even if one entry fails
Response
201 - Objects Created
failed_grc_object_name
string
GRC Object name that got failed on partial success scenario. This field is only valid in case of request has query parameter with proceedOnError flag as false.
not_processed_grc_object_names
array
Collection of GRC Objects names not processed on partial success scenario
succeeded_grc_objects
array
Collection of created GRC Objects. On partial failure scenario, This field will have Collection of GRC Objects Got created.
POST /v2/contents
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. To convert PDF document to base64, save the pdf file(MyTestPdf.pdf) in a folder. Depending on your operating system, you can use a tool to convert a file to base64. For example on Mac OSX or Linux, open terminal in that folder and use base64 command base64 -i MyTestPdf.pdf > pdfToBase64 Open the new file(pdfToBase64), copy the contents and set it in the `content_definition.children` attribute.
Auditing
Calling this method generates the following auditing event.
openpages.resource.create
Request
Request Body
DocumentCreateType
Creates a GRC object.
file_type_definition
file_type_definition_type
Defines a File Type definition
id
Required *
string
Filetype definition type ID
file_extension
Required *
string
File extension
mime_type
Required *
string
Mime type
content_definition
ContentDefinitionType
Defined a Content definition type
attribute
Required *
object
Defines an File content type
children
Required *
string
For plain text files, plain String value representing the contents of the text file being uploaded. For other file types, this field should contain Base64 encoded file contents.
name
Required *
string
Resource Name
id
string
Resource ID
path
string
Resource Path
description
string
Description
title
string
Resource Title
creator
string
Resource Creator
fields
array
Fields in this Object type
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
parent_folder_id
string
Parent Folder ID
last_modified_by
string
Resource last modified by
type_definition_id
Required *
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
Path Parameters
Query Parameters
append_enum_vals
boolean
Flag to create enum if it doesn't exist
Response
201 - Object Created
name
string
Resource Name
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
fields
array
Collection of Fields defined in this Object type
type_definition_id
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
title
string
Resource Title
workflow_activity_ids
array
List of workflow process ids.
Get GRC Object by ID
GET /v2/contents/{id}
Gets a GRC Object instance by ID or a relative path. Use optional parameters to control data returned.
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
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.
include_associations
string
Associations to other GRC Objects. Defaults to none for optimal performance.
include_workflow
string
Include associated workflow information.
associationtype_filters
string
If including Associations, specify the list of Object Types to include.
reporting_period_label
string
The Reporting Period name to retrieve the GRC Object from a particular period. Default is from the Current Period.
evaluate_computed_fields
string
Computed fields are not evaluated by default. To include evaluated calculations in the response, set to true.
Response
200 - 200
name
string
Resource Name
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
fields
array
Collection of Fields defined in this Object type
type_definition_id
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
title
string
Resource Title
workflow_activity_ids
array
List of workflow process ids.
Update GRC Object
PUT /v2/contents/{id}
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.update
Request
Request Body
DocumentCreateType
Update GRC object
file_type_definition
file_type_definition_type
Defines a File Type definition
id
Required *
string
Filetype definition type ID
file_extension
Required *
string
File extension
mime_type
Required *
string
Mime type
content_definition
ContentDefinitionType
Defined a Content definition type
attribute
Required *
object
Defines an File content type
children
Required *
string
For plain text files, plain String value representing the contents of the text file being uploaded. For other file types, this field should contain Base64 encoded file contents.
name
Required *
string
Resource Name
id
string
Resource ID
path
string
Resource Path
description
string
Description
title
string
Resource Title
creator
string
Resource Creator
fields
array
Fields in this Object type
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
parent_folder_id
string
Parent Folder ID
last_modified_by
string
Resource last modified by
type_definition_id
Required *
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
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
Query Parameters
append_enum_vals
boolean
Flag to create enum if it doesn't exist
Response
200 - 200
name
string
Resource Name
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
fields
array
Collection of Fields defined in this Object type
type_definition_id
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
title
string
Resource Title
workflow_activity_ids
array
List of workflow process ids.
Delete Resource
DELETE /v2/contents/{id}
Performs a "soft delete" on a GRC Object instance by ID. Information can be retrieved using the Find Deleted Resources endpoint.
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.
Query Parameters
Response
204 - GRC Object deleted successfully. No Content.
Find Deleted Resources
GET /v2/contents/deletedresources
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.list
Request
Path Parameters
Query Parameters
filter
string
A filter to limit deleted resource results. For example, `filter=Description like 'name'`.
start_row
integer
Paging start row index
end_row
integer
Paging end row index
Response
200 - 200 OK
deleted_resources
array
Collection of Deleted ResourceTypes
GRC Object Can Create Child of Type
GET /v2/contents/{id}/permissions/cancreate/{type}
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-permission.get
Request
Path Parameters
id
Required *
string
GRC Object ID or Path
type
Required *
string
The child Object Type.
Query Parameters
folder
string
The folder ID to use when checking permissions. If null, use the default folder.
Response
200 - 200 OK
response
string
REST response field
Get GRC Object Child Association by ID
GET /v2/contents/{id}/associations/children/{child_id}
Gets the details of a GRC Object Child Association by the specified 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
child_id
Required *
string
The ID of the child object that is associated with this GRC Object.
Query Parameters
Response
200 - 200
id
string
Object ID
type_definition_id
string
Object Type definition ID
path
string
Object Path
association_definition_id
string
Association Definition ID
type
string
Association Type
404 - Child ID not found.
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get Document Content as Stream
GET /v2/contents/{id}/document
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.
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.
Query Parameters
mime_type
string
MIME Type of the content in the response.
Response
200 - 200 OK
Update Document with Stream
PUT /v2/contents/{id}/document
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. To update PDF file, execute below command curl -X PUT --location --header "Authorization: Basic ${basic auth}" --header "Content-Type: application/pdf" https://my-op-server:10111/opgrc/api/v2/contents/${id}/document --data-binary @path/MyTest.pdf where {id} is the id of the original pdf file, MyTest is the pdf with updated content and path is the actual path to MyTest.pdf(Do NOT remove @)
Auditing
Calling this method generates the following auditing event.
openpages.file-resource.upload
Request
Request Body
Path Parameters
id
Required *
string
The Document ID or path
Query Parameters
Response
202 - Document updated successfully.
GRC Object Effective Permissions
GET /v2/contents/{id}/permissions/effective
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-permission.get
Request
Path Parameters
id
Required *
string
GRC Object ID or Path
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.
Response
200 - 200 OK
folder_id
string
Folder ID
security_principal
string
Security Principal
can_read
boolean
Indicate if principal can read resource
can_write
boolean
Indicate if principal can write resource
can_delete
boolean
Indicate if principal can delete resource
can_associate
boolean
Indicate if principal can associate resources
Get New GRC Object Template
GET /v2/contents/template
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-template.get
Request
Path Parameters
Query Parameters
type_id
Required *
string
Object Type system name or ID for the new template.
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.
Response
200 - 200
name
string
Resource Name
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
fields
array
Collection of Fields defined in this Object type
type_definition_id
string
Object Type's ID or System name
is_checkout
boolean
Is Object checked out
is_locked
boolean
Is Object locked
primary_parent_id
string
Another GRC Object's resource ID or full path
title
string
Resource Title
workflow_activity_ids
array
List of workflow process ids.
Get GRC Object Parent Association by ID
GET /v2/contents/{id}/associations/parents/{parent_id}
Gets the details of a GRC Object Parent Association.
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
parent_id
Required *
string
The ID of the parent object that is associated with this GRC Object.
Query Parameters
Response
200 - 200
id
string
Object ID
type_definition_id
string
Object Type definition ID
path
string
Object Path
association_definition_id
string
Association Definition ID
type
string
Association Type
Get Report Fragment
GET /v2/contents/{id}/report/{field_name}
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.
Auditing
Calling this method generates the following auditing event.
openpages.report-fragment.report
Request
Path Parameters
id
Required *
string
GRC Object ID or Path
field_name
Required *
string
System name of the report fragment field.
Query Parameters
Response
200 - 200 OK
id
string
Field ID
data_type
string
Field Data Type
name
string
Field name
has_changed
boolean
Has field value changed
value
string
String field value
Get Association Audit Logs
GET /v2/contents/{id}/associations/auditlogs
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-activity.list
Request
Path Parameters
id
Required *
string
GRC Object ID or Path
Query Parameters
association_filters
string
A comma-delimited list of type names. Use to determine which object types to retrieve from associations.
startdate
string
Start of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"
enddate
string
End of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"
Response
200 - 200
auditlogs
array
Collection of Association Audit Logs
Get fields Audit Log
GET /v2/contents/{id}/fields/auditlogs
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-activity.list
Request
Path Parameters
id
Required *
string
GRC Object ID or Path
Query Parameters
field_filters
string
A comma-delimited list of field system names. Use to determine which field logs to retrieve.
start_date
string
Start of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"
end_date
string
End of date range in audit logs. Accepts ISO8601 date format. "yyyMMdd'T'HHmmssZ"
Response
200 - 200
auditlogs
array
Collection of Field Audit Logs
Lock GRC Object
PUT /v2/contents/{id}/action/lock
Locks a GRC Object.
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
Query Parameters
Response
202 - GRC Object locked successfully.
Move GRC Objects
PUT /v2/contents/{id}/action/move
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource-move.commit
Request
Request Body
ActionType
Request body containing the list of Object IDs to be moved and options for the move action
ids
Required *
array
Collection of Object IDs
options
Required *
OptionType
Defines Action Option Type
include_children
boolean
Flag to include Children Objects in the action or not
conflict_behavior
Required *
string
Specifies the desired behavior when a GRCObject with the same name already exists in the target location
type_definitions
Required *
array
type_definitions
type_associations
Required *
array
Specifies the list of object type associations that need to be honored during the Action
auto_name_children
boolean
Flag to specify if the associated children of the source GRCObject should be autoNamed or not when copied.
Path Parameters
id
Required *
string
Parent GRC Object ID or Path to move the Objects to
Query Parameters
Response
202 - Moved list of GRC Objects successfully.
Overwrite Field Values
PUT /v2/contents/{id}/action/overwriteproperties
Overwrites text fields of a object with a specific value and also overwrites references to those fields on the Activity Tab. 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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.update
Request
Path Parameters
id
Required *
string
GRC Object ID
Query Parameters
fields
Required *
string
Comma-delimited list of field definition IDs for the fields to be overwritten.
value
Required *
string
New value to replace the existing value. Must not be empty.
Response
202 - Field values updated successfully.
Purge Resource
DELETE /v2/contents/{id}/action/purge
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.
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
Query Parameters
Response
204 - Resource purged successfully. No Content.
Remove All Locks
DELETE /v2/contents/{id}/action/remove_all_locks
Removes all locks from the specified GRC Object and from the hierarchy below the specified GRC Object.
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
Query Parameters
Response
204 - Unlocked the GRC Object and descendant Objects successfully. No Content.
Unlock GRC Object
PUT /v2/contents/{id}/action/unlock
Unlocks a GRC Object if it is locked.
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
Query Parameters
Response
202 - GRC Object unlocked successfully.
FastMap import
POST /v2/fastmap/import
Loads the contents of an XLSX FastMap template.
Auditing
Calling this method generates the following auditing event.
openpages.fastmap-resource.import
Request
Request Body
Path Parameters
Query Parameters
file_name
string
The XLSX file name, including the .xlsx extension.
stop_on_warnings
string
If User name is a numeric value then isName should be true.
Response
200 - 200
type
string
description
string
row
integer
column_name
string
column_index
string
sheet_name
string
FastMap validate
POST /v2/fastmap/validate
Validates the contents of an XLSX FastMap template.
Auditing
Calling this method generates the following auditing event.
openpages.fastmap-resource.validate
Request
Request Body
Path Parameters
Query Parameters
file_name
string
The XLSX file name, including the .xlsx extension.
Response
200 - 200
messages
array
summary_messages
array
Get Root Folder
GET /v2/folders
Gets the root Folder resource for OpenPages with full path of "/"
Auditing
Calling this method generates the following auditing event.
openpages.root-folder.get
Request
Response
200 - 200
folders
array
Collection of FolderTypes
Create New Folder
POST /v2/folders
Creates a Folder. To use a template folder to construct the request body, see the GET /folders/template operation.
Auditing
Calling this method generates the following auditing event.
openpages.folder.create
Request
Request Body
FolderType
Create a Folder.
name
Required *
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Response
201 - Created Folder
name
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Get Folder by ID
GET /v2/folders/{folder_id}
Gets specific Folder resource information by ID.
Auditing
Calling this method generates the following auditing event.
openpages.folder.get
Request
Path Parameters
folder_id
Required *
string
Folder ID
Query Parameters
Response
200 - 200
name
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Update Folder
PUT /v2/folders/{folder_id}
Updates an existing Folder.
Auditing
Calling this method generates the following auditing event.
openpages.folder.update
Request
Request Body
FolderType
Update an existing Folder
name
Required *
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Path Parameters
folder_id
Required *
string
ID of Folder to be updated
Query Parameters
Response
200 - 200
name
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Delete Folder
DELETE /v2/folders/{folder_id}
Deletes a Folder and all of its contents. Cannot be undone.
Auditing
Calling this method generates the following auditing event.
openpages.folder.delete
Request
Path Parameters
folder_id
Required *
string
ID of Folder to delete
Query Parameters
Response
204 - The folder was deleted successfully. No Content.
Get Effective Permissions
GET /v2/folders/{folder_id}/permissions/effective
Gets the effective permissions (ACL) for a user on a GRC Object resource. Example path for GET request: `/folders/1234/effectivePermissions?user=bill`
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.
Query Parameters
user
string
User name or ID. If a value is not specified, the effective permissions for the current user are retrieved.
Response
200 - 200
folder_id
string
Folder ID
security_principal
string
Security Principal
can_read
boolean
Indicate if principal can read resource
can_write
boolean
Indicate if principal can write resource
can_delete
boolean
Indicate if principal can delete resource
can_associate
boolean
Indicate if principal can associate resources
Get New Folder Template
GET /v2/folders/template
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.
Auditing
Calling this method generates the following auditing event.
openpages.folder-template.get
Request
Response
200 - 200
name
string
Resource Name
title
string
Resource Title
id
string
Resource ID
path
string
Resource Path
is_folder
boolean
Is Folder
creation_date
string
Creation Date
modified_date
string
Modified Date
description
string
Description
parent_folder_id
string
Parent Folder ID
creator
string
Resource Creator
last_modified_by
string
Resource last modified by
Get Folder Resources
GET /v2/folders/{folder_id}/resources
Gets all resources contained in a folder. Results can be either GRC Object content or other Folders.
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.
Query Parameters
include_containees
string
Which types of contained resources to return.
offset
integer
0-based index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
resources
array
Collection of ResourceType Objects
Get Contents of Log Zip File
GET /v2/logs/collector/download/{zip_object_id}
Gets the contents of the file containing the logs. The contents are returned as a octet-stream.
Auditing
Calling this method generates the following auditing event.
openpages.logs-download.get
Request
Path Parameters
zip_object_id
Required *
integer
The zipObjectId used to fetch the corresponding logs.
Query Parameters
Response
200 - 200 OK
Get subprocess Details for a process.
GET /v2/logs/collect/{process_id}
Gets the process details for the logs.
Auditing
Calling this method generates the following auditing event.
openpages.logs-collect.get-subprocesses
Request
Path Parameters
process_id
Required *
integer
Used to fetch the subprocess.
Query Parameters
Response
200 - 200
processes
array
Collection of log subprocess
Start Logging Process
POST /v2/logs/collect
Starts the log collecting process by specifying the type of logs to be included, such as db, app, or all.
Auditing
Calling this method generates the following auditing event.
openpages.log-collect.add
Request
Path Parameters
Query Parameters
include
Required *
string
Set the type of logs to be collected. Must be app, db, or all.
Response
200 - 200
downloadable
boolean
process_id
integer
object id
zip_object_id
integer
zip object id
process_type_id
integer
process type id
process_type_label
string
process type label
name
string
name
created_on
string
formatted_created_on_date
string
is_finished
boolean
percent_complete
integer
Percentage of completion
description
string
description
status
integer
Status
status_name
string
status name
parent_process_name
string
parent process name name
create_by
string
create by
modify_date
string
modify date
custom_data
object
custom data
is_downloadable
boolean
is downloadable
file_size
integer
file size
parent_process_id
integer
parent process id
Get Latest Process for Type
GET /v2/processes/latest/{process_type_id}
Gets the latest specific Process instance information by 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
Query Parameters
Response
200 - 200
process_id
string
Process ID
name
string
Process name
description
string
Process description
process_type_id
string
Process Type ID
finished
boolean
Flag to indicate if process finished
created_on
string
Process created date
created_by
string
Process created by
status
string
Process status
parent_process_id
string
Parent process id
percent_complete
integer
Describes process percentage completion
child_processes
array
Lists child processes
Get a Process
GET /v2/processes/{process_id}
Gets a specific Process instance by ID.
Auditing
Calling this method generates the following auditing event.
openpages.process.get
Request
Path Parameters
process_id
Required *
string
Process instance ID
Query Parameters
include_child_processes
boolean
Specifies whether the response should include child processes
Response
200 - 200
process_id
string
Process ID
name
string
Process name
description
string
Process description
process_type_id
string
Process Type ID
finished
boolean
Flag to indicate if process finished
created_on
string
Process created date
created_by
string
Process created by
status
string
Process status
parent_process_id
string
Parent process id
percent_complete
integer
Describes process percentage completion
child_processes
array
Lists child processes
Terminate a Process
PUT /v2/processes/{process_id}
Terminates a Process instance. Stops the process instance execution and cannot be undone.
Auditing
Calling this method generates the following auditing event.
openpages.process.stop
Request
Path Parameters
process_id
Required *
string
Process instance ID
Query Parameters
action
Required *
string
The terminate action to perform
Response
202 - Process successfully terminated.
400 - 400
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get Process Logs
GET /v2/processes/{process_id}/logs
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.
Auditing
Calling this method generates the following auditing event.
openpages.process-log.list
Request
Path Parameters
process_id
Required *
string
Process instance ID
Query Parameters
include_localized_status
boolean
Specifies whether the response should include localized status labels
offset
integer
Number of log records to skip
limit
integer
Page size
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
process_logs
array
Collection of ProcessLogType
Get all Process Types
GET /v2/processes/processtypes
Gets all Process Types in the Long Running Process Framework (LRPF).
Auditing
Calling this method generates the following auditing event.
openpages.process-type.list
Request
Response
200 - All Process Types
processtypes
array
Collection of ProcessTypeType Objects
Get a list of Processes
GET /v2/processes
Gets a list of Process instances by ID.
Auditing
Calling this method generates the following auditing event.
openpages.process.list
Request
Path Parameters
Query Parameters
process_id
string
Process instance ID
parent_process_id
string
The parent Process ID of queried processes
process_type_id
string
The Process type id of queried processes
status
string
The Process status of queried processes in a comma-separated list
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".
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".
created_by
string
The user who created the queried processes
Response
200 - 200
processes
array
Collection of ProcessInfoType
Query Service - Get
GET /v2/query
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 (\).
Auditing
Calling this method generates the following auditing event.
openpages.resource.query
Request
Path Parameters
Query Parameters
q
Required *
string
Query statement. Is required and must follow Query-Service syntax.
offset
integer
Number of results to be skipped. Used for paging.
case_insensitive
boolean
Specify if string comparisons should be case-insensitive. Applies to all comparisons in WHERE clause.
limit
integer
Number of results to return, starting from offset.
max_rows
integer
Maximum number of results the query service retrieves from the database. Use 0 for all rows.
honor_primary
boolean
If JOIN syntax is used between Object Types, specifies whether to restrict to only include primary associations.
Response
200 - 200
definitions
array
Collection of results field definitions
rows
array
Collection of result rows
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Query Service - Post
POST /v2/query
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 <code>\\'</code>, while with curl command or any other API test tools the single quotes needs to be escaped with three backslash.
Auditing
Calling this method generates the following auditing event.
openpages.resource.query
Request
Request Body
QueryType
statement
Required *
string
Query statement
offset
Required *
integer
Specifies the starting result row
case_insensitive
boolean
To set string-type conditions case-insensitive, default is false.
limit
integer
Number of rows per page
max_rows
Required *
integer
Total number of rows returned by the query
honor_primary
boolean
Only include primary associations
Response
200 - 200
definitions
array
Collection of results field definitions
rows
array
Collection of result rows
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
Get Results from Global Search
GET /v2/search
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.search
Request
Path Parameters
Query Parameters
q
Required *
string
Search terms
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#`
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.
mode
string
Global Search mode. Reserved for future use.
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.
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)
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
ffp
string
Faceted Search by Folder Path. Use relative paths starting from below the Object type root folder.
fmt
string
Faceted Search by MIME type. Applies to file attachment search. Comma-delimited list of MIME Media types.
Response
200 - Search results
search_id
string
Search ID
estimated_results
integer
Estimated results size
result_list
array
Collection of Search results
400 - Search parameters not provided in request body
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Global Search - Post
POST /v2/search
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.
Auditing
Calling this method generates the following auditing event.
openpages.resource.search
Request
Request Body
SearchType
Search parameters
q
Required *
string
Search string
search_id
string
Search id
types
string
Object Types to include in search
mode
string
Global Search mode
page
Required *
integer
page
page_size
Required *
integer
page size
fot
string
Faceted Search by Object Types
fur
string
Faceted Search by Users
fdt
string
Faceted Search by Date
ffp
string
Faceted Search by Folder Path
fmt
string
Search fmt to specify MIME Media types
Response
200 - Search results
search_id
string
Search ID
estimated_results
integer
Estimated results size
result_list
array
Collection of Search results
400 - Search parameters not provided in request body
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Run routing rules for given object IDs
POST /v2/rules/run
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.
Auditing
Calling this method generates the following auditing event.
openpages.rule.evaluate
Request
Request Body
tbrules_runrules_request_type
object_ids
Required *
array
Object IDs
Response
200 - 200
successful_objects
array
List of successful Object IDs
failed_objects
array
List of failed Object IDs
Get Association Definition by ID
GET /v2/types/{type_id}/associations/{association_id}
Gets an association definition for an Object Type by the association's 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
association_id
Required *
string
Association definition ID
Query Parameters
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale
Response
200 - 200 OK
id
string
Association definition type ID
name
string
Association definition type name
localized_label
string
Association definition type localized label
localized_labels
array
Collection of Localized Label
localized_plural_label
string
localized plural label
localized_plural_labels
array
Collection of Localized Plural Label
association_definition_id
string
Association definition id
max
integer
Maximum number of associations
min
integer
Minimum number of associations
is_enabled
boolean
Is enabled
relationship
string
Relationship type
404 - Object Type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get all Non provisioned Solutions Usage
GET /v2/types/usages/unclaimed
Gets all Non provisioned Solutions Usage.
Auditing
Calling this method generates the following auditing event.
openpages.object-type-unclaimed.get
Request
Response
200 - 200 OK
solution_usages
array
Collection of NonProvisionSolutionAssetUsage
404 - Solution usage not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get an Object Type by ID
GET /v2/types/{type_id}
Gets an Object Type. Use optional parameters to control what data is returned.
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
Query Parameters
include_field_definitions
boolean
Include Field definitions
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale
Response
200 - 200 OK
id
string
Type definition ID
name
string
Type name
localized_label
string
Localized label on this type
localized_labels
array
Collection of Localized Label
localized_plural_label
string
Localized Plural label on this type
localized_plural_labels
array
Collection of Localized Plural Label
description
string
Type description
jsp_path
string
JSP path to render this type
root_folder_path
string
Path of the Root Folder
root_folder_id
string
Resource ID of the Root Folder
field_definitions
array
List of fields under this type
file_types
array
Collection of File Type
404 - Object Type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get Object Type Associations
GET /v2/types/{type_id}/associations
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.
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
Query Parameters
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale
association_type
string
Filters object associations based on association type. Value can be parent or child.
Response
200 - 200 OK
associations
array
Collection of Association Definition Type
404 - Object Type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get all Object Types
GET /v2/types
Gets a list of all GRC Object Types. Use optional parameters to control data returned.
Auditing
Calling this method generates the following auditing event.
openpages.object-type.list
Request
Path Parameters
Query Parameters
include_field_definitions
boolean
Include Field definitions
include_localized_labels
boolean
Include Labels for all Locales or only the labels for current user's locale
Response
200 - List all Object Types.
types
array
Collection of TypeDefinitions
Process bulk request
POST /v2/scim/Bulk
Processes a bulk request.
Request
Request Body
SCIMBulkRequest
Processes a bulk request.
id
Required *
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
resourceType
string
The name of the resource type of the resource
created
string
The "DateTime" that the resource was added to the service provider
lastModified
string
The most recent DateTime that the details of this resource were updated at the service provider
location
string
The URI of the resource being returned
version
string
The version of the resource being returned
schemas
Required *
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
failOnErrors
integer
Number of errors before halting processing.
Operations
array
List of bulk operations.
Response
200 - 200 OK
schemas
array
Operations
array
List of bulk operations.
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 top level groups
GET /v2/scim/Groups
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
Auditing
Calling this method generates the following auditing event.
openpages.group.list
Request
Path Parameters
Query Parameters
filter
string
Filter expression used to request a subset of resources
attributes
string
Comma-separated list of resource attribute names to be returned in response
sortOrder
string
Specifies sort order. Values are 'ascending' or 'descending'.
sortBy
string
Resource attribute name to sort on.
startIndex
integer
1-based index of the first query result
count
integer
Specifies the desired maximum number of results per page
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
string
A human-readable name for the Group
members
array
A list of members of the Group
Create group
POST /v2/scim/Groups
Creates a group.
Auditing
Calling this method generates the following auditing event.
openpages.group.create
Request
Request Body
SCIMGroup
Create a group.
id
Required *
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
resourceType
string
The name of the resource type of the resource
created
string
The "DateTime" that the resource was added to the service provider
lastModified
string
The most recent DateTime that the details of this resource were updated at the service provider
location
string
The URI of the resource being returned
version
string
The version of the resource being returned
schemas
Required *
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
Required *
string
A human-readable name for the Group
members
Required *
array
A list of members of the Group
Response
200 - 200
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
string
A human-readable name for the Group
members
array
A list of members of the Group
Get Group
GET /v2/scim/Groups/{id}
Gets a Group by the specified 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
isName
string
If Group name is a numeric value then isName should be true.
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
string
A human-readable name for the Group
members
array
A list of members of the Group
404 - Requested object not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Update Group
PUT /v2/scim/Groups/{id}
Replaces an existing Group.
Auditing
Calling this method generates the following auditing event.
openpages.group.update
Request
Request Body
SCIMGroup
Replace all attributes of an existing group with the request payload
id
Required *
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
resourceType
string
The name of the resource type of the resource
created
string
The "DateTime" that the resource was added to the service provider
lastModified
string
The most recent DateTime that the details of this resource were updated at the service provider
location
string
The URI of the resource being returned
version
string
The version of the resource being returned
schemas
Required *
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
Required *
string
A human-readable name for the Group
members
Required *
array
A list of members of the Group
Path Parameters
id
Required *
string
Group name or ID.
Query Parameters
isName
string
If Group name is a numeric value, set isName to true.
Response
200 - 200
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
string
A human-readable name for the Group
members
array
A list of members of the Group
Patch Group
PATCH /v2/scim/Groups/{id}
Patches an existing Group.
Auditing
Calling this method generates the following auditing event.
openpages.group.update
Request
Request Body
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
schemas
array
Operations
array
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
isName
string
If Group name is a numeric value then isName should be true.
Response
200 - 200
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
displayName
string
A human-readable name for the Group
members
array
A list of members of the Group
Get resource types
GET /v2/scim/ResourceTypes
Gets all resource types.
Auditing
Calling this method generates the following auditing event.
openpages.scim-resource-type.get
Request
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
totalResults
integer
startIndex
integer
itemsPerPage
integer
Resources
array
Get resource type by name
GET /v2/scim/ResourceTypes/{resource_name}
Gets a specific resource type by name.
Auditing
Calling this method generates the following auditing event.
openpages.scim-resource-type.get
Request
Path Parameters
resource_name
Required *
string
Query Parameters
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
name
string
description
string
endpoint
string
schema
string
schemaExtensions
array
404 - Requested Resource type not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Get schema by id
GET /v2/scim/Schemas/{schema_id}
Gets a schema by the schema URI of the schema definition.
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
Query Parameters
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
name
string
description
string
attributes
array
List all schemas
GET /v2/scim/Schemas
List SCIM schemas of all resources and extensions.
Auditing
Calling this method generates the following auditing event.
openpages.scim-schema.list
Request
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
totalResults
integer
startIndex
integer
itemsPerPage
integer
Resources
array
Get service provider configuration
GET /v2/scim/ServiceProviderConfig
Gets a JSON structure that describes the SCIM specification features available on service provider.
Auditing
Calling this method generates the following auditing event.
openpages.scim-service-provider-configuration.get
Request
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
documentationUrl
string
patch
Configuration
bulk
BulkConfiguration
filter
FilterConfiguration
changePassword
Configuration
sort
Configuration
etag
Configuration
authenticationSchemes
array
attributes=displayName,description
attributes=name.familyName,groups,description,preferredProfileName
attributes=availableProfileNames is not supported. Refer Get User API(/v2/scim/Users/{id}) to view availableProfileNames in the response.
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
">
List users
GET /v2/scim/Users
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
attributes=availableProfileNames is not supported. Refer Get User API(/v2/scim/Users/{id}) to view availableProfileNames in the response.
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
Auditing
Calling this method generates the following auditing event.
openpages.user.list
Request
Path Parameters
Query Parameters
filter
string
Filter string used to request a subset of resources
attributes
string
Comma separated list of resource attribute names to be returned in response
sortOrder
string
Specifies sort order. Values are 'ascending' or 'descending'
sortBy
string
Resource attribute name to sort on.
startIndex
integer
1-based index of the first query result
count
integer
Specifies the desired maximum number of results per page
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
string
Unique identifier for the User
name
Name
The components of the user's name
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
Create user
POST /v2/scim/Users
Creates a user.
Auditing
Calling this method generates the following auditing event.
openpages.user.create
Request
Request Body
SCIMUser
Creates a user.
id
Required *
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
resourceType
string
The name of the resource type of the resource
created
string
The "DateTime" that the resource was added to the service provider
lastModified
string
The most recent DateTime that the details of this resource were updated at the service provider
location
string
The URI of the resource being returned
version
string
The version of the resource being returned
schemas
Required *
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
Required *
string
Unique identifier for the User
name
Name
The components of the user's name
familyName
string
The family name of the User, or Last Name
givenName
string
The given name of the User, or First Name
middleName
string
The middle name(s) of the User
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
string
Unique identifier for the User
name
Name
The components of the user's name
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
Get user
GET /v2/scim/Users/{id}
Gets a user by ID or userName.
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.
attributes
string
Comma separated list of resource attribute names to be returned in response
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
string
Unique identifier for the User
name
Name
The components of the user's name
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
404 - Requested object not found
status_code
string
HTTP status code used for the response
errors
array
Collection of errors
trace
string
Unique ID to identify the request.
Update user
PUT /v2/scim/Users/{id}
Replace an existing user with the user request.
Auditing
Calling this method generates the following auditing event.
openpages.user.update
Request
Request Body
SCIMUser
Replace all attributes of an existing user with the request payload
id
Required *
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
resourceType
string
The name of the resource type of the resource
created
string
The "DateTime" that the resource was added to the service provider
lastModified
string
The most recent DateTime that the details of this resource were updated at the service provider
location
string
The URI of the resource being returned
version
string
The version of the resource being returned
schemas
Required *
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
Required *
string
Unique identifier for the User
name
Name
The components of the user's name
familyName
string
The family name of the User, or Last Name
givenName
string
The given name of the User, or First Name
middleName
string
The middle name(s) of the User
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
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.
Response
200 - 200 OK
id
string
A unique identifier for a SCIM resource
meta
SCIMMeta
A complex attribute containing resource metadata
schemas
array
List of URIs that are used to indicate the namespaces of the SCIM schemas
userName
string
Unique identifier for the User
name
Name
The components of the user's name
displayName
string
locale
string
Used to indicate the User's default location
active
boolean
Indicates user's administrative status
password
string
emails
array
Email addresses for the User
groups
array
Groups this user is part of
Patch User
PATCH /v2/scim/Users/{id}
Updates the attributes of an existing user. Can be used to update roles for a user. For more details on the format of the patch request, refer https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2
Auditing
Calling this method generates the following auditing event.
openpages.user.update
Request
Request Body
PatchRequest
Patches an existing user
schemas
array
Operations
array
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.
attributes
string
Comma separated list of resource attribute names to be returned in response
Response
default - 200
Retrieve workflow instance data for the given workflow instance id
GET /v2/workflows/instances/{id}
Retrieve workflow instance data for the given workflow instance id.
Auditing
Calling this method generates the following auditing event.
openpages.workflow-resource.get
Request
Path Parameters
id
Required *
string
The Activity Instance id.
Query Parameters
Response
200 - 200
id
string
WorkFlow activity instance id
status
string
WorkFlow activity instance status
criticality
string
WorkFlow activity instance criticality
due_date
string
Workflow Due Date
assignees
array
Assignees
process_start_date
string
Workflow prcoess Start Date
process_due_date
string
Workflow process Due Date
grc_object
workflow_activity_instance_grc_object_data_type
The workflow activity instance grc object data type definition.
workflow
workflow_data_type
Activity instance workflow data type definition.
Get Workflow Process Definition by Id
GET /v2/workflows/definitions/{id}
Returns a workflow process definition given it's id.
Auditing
Calling this method generates the following auditing event.
openpages.workflow.get
Request
Path Parameters
id
Required *
string
The Workflow definition id.
Query Parameters
Response
200 - 200
id
string
Workflow Definition ID
name
string
Workflow Definition Name
label
string
Workflow Definition Label
version_id
string
Workflow Definition Version ID
type_definition_name
string
Object Type's Name
type
string
Type of workflow
version_number
string
Version number
latest_version_number
string
Latest version number for the workflow definition
state
string
State of this version of the workflow
last_version_state
string
State of the latest version of the workflow
is_automated
boolean
Is Workflow automated
is_enabled
boolean
Is Workflow enabled
last_modified_by
string
Workflow last modified by
modified_on
string
Modification date
created_by
string
Workflow Creator
created_on
string
Created on date
activities
array
Lists workflow activities
Get Workflow Process Definition by Version Id
GET /v2/workflows/definitions/version/{id}
Returns a workflow process definition given it's versionid.
Auditing
Calling this method generates the following auditing event.
openpages.workflow-version.get
Request
Path Parameters
id
Required *
string
The Workflow definition version id.
Query Parameters
Response
200 - 200
id
string
Workflow Definition ID
name
string
Workflow Definition Name
label
string
Workflow Definition Label
version_id
string
Workflow Definition Version ID
type_definition_name
string
Object Type's Name
type
string
Type of workflow
version_number
string
Version number
latest_version_number
string
Latest version number for the workflow definition
state
string
State of this version of the workflow
last_version_state
string
State of the latest version of the workflow
is_automated
boolean
Is Workflow automated
is_enabled
boolean
Is Workflow enabled
last_modified_by
string
Workflow last modified by
modified_on
string
Modification date
created_by
string
Workflow Creator
created_on
string
Created on date
activities
array
Lists workflow activities
Get Workflow Process Definitions
GET /v2/workflows/definitions
Returns all workflow process definitions. Use optional parameter to filter by object type.
Auditing
Calling this method generates the following auditing event.
openpages.workflow.list
Request
Path Parameters
Query Parameters
object_type
string
The GRC object type to return workflows for. Can be an id or a name.
include_activities
string
Activities and actions are included by default. Set this to false to filter them out.
Response
200 - 200
total_count
integer
Total number of records
offset
integer
Specify index of the first query result.
limit
integer
Specifies the desired maximum number of results per page.
definitions
array
Collection of WFProcessDefinitionType
Transition GRC Object to New Workflow State
POST /v2/workflows/instances/{id}/transition/{transition}
Transitions a GRC object to the new workflow state based on the instance ID and transition name.
Auditing
Calling this method generates the following auditing event.
openpages.workflow-resource.commit
Request
Path Parameters
id
Required *
string
The Workflow instance id.
transition
Required *
string
The name of the Workflow action to perform.
Query Parameters
Response
200 - Successfully ran the workflow on the GRC object, transitioning the GRC object to the new state.
Retrieve workflow instances using search parameters
GET /v2/workflows/instances/search
Returns all workflow process instance data based on the search parameter.
Auditing
Calling this method generates the following auditing event.
openpages.workflow-resource.search
Request
Path Parameters
Query Parameters
sort_field
string
Field to sort results by.
sort_direction
string
Direction to sort results. asc or desc
user_role
string
User's role to filter on.
user
string
User to filter on. Can be username or id.
type_definition
string
Type Definition to filter on. Can be name or id.
workflow
string
Workflow to filter on. Can be name or id.
include_counts
string
Whether to return due date result counts with the list of activity instances
group_dimension
string
Dimension to group due date counts by.
date_interval
string
The scope to aggregate due date counts.
offset
string
The page of results to return.
limit
string
The max number of results returned by each request.
Response
200 - 200
activity_instances
array
Collection of workflow activity instances.
counts
array
Counts of activity instances by due date and optional dimension.
paging
PagedCollection
Pagination data
Start the workflow process for the given workflow id and grc object id
POST /v2/workflows/definitions/{id}/start/{grc_object_id}
Start the workflow process for the given workflow id and 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.
grc_object_id
Required *
string
The Grc Object id.