Skip to Content

REST properties

Properties are named variables that can be assigned property values (polymorphic) for themselves (default values), Installed Components, Application Components, Requests, Servers, Server Aspects, and Server Levels.

Warning

Notes

  • A property value is a related model to properties but it should not be updated and manipulated directly. Add or change a property value through the parent property model, because special getters and setters ensure that prior values are time-stamped as deleted_at to maintain a clear audit record of property value changes.
  • Properties can be marked as private by setting their is_private attribute to true. In the user interface, this means that the property value will be obscured with ****. The REST API, however, is primarily for computer-to-computer transactions and sends even private values in plain text so that their values can be used by the consuming interface. Values that must be completely secure should be stored in an external repository and retrieved using a secure mechanism, rather than simple privacy screening.
  • The include_except and alone filters are available in only 5.0.03.004 and later versions of BRPM. Use these filters to limit the data in API response and hence, reduce the API response time.

GET /v1/properties

Returns all properties.

Filters

  • active — Boolean value for active properties only (default is true, showing active only by default)
  • app_name — String for the application name
  • component_name — String for the component name
  • current_value — String for the value among current property values (that is, deleted_at = null)
  • deleted_value — String for the value among deleted property values (that is, deleted_at != null)
  • inactive — Boolean value for inactive properties (when used with active = false, can be used to show just inactive properties)
  • name — String for property name
  • server_level_name — String for the server level name
  • server_name — String for the server name
  • work_task — String for the work task name
  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items.

Item

Associated items

properties

current_property_values, deleted_property_values, work_tasks, components, packages, server_levels, servers, apps

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not Found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/properties?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/properties?token=[api_token]

Filters examples:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "filters": { "name":"Server Login" }}' http://[rails_host]/v1/properties?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "filters": { "include_except": "work_tasks,components,packages" }}' https://[rails_host]/v1/properties?token=[api_token]

GET /v1/properties/[id]

Returns a property by ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items.

Item

Associated items

properties

current_property_values, deleted_property_values, work_tasks, components, packages, server_levels, servers, apps

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to show is not found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/properties/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/properties/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except": "work_tasks,components,packages" }}' https://[rails_host]/v1/properties/[id]?token=[api_token]

POST /v1/properties

Creates a new property from posted data.

Required attributes

  • name — String name (required)

Optional attributes

  • default_value — String default value for a property
  • is_private — Boolean value for whether the display of property values should be obscured with **** (defaults to nil or false)
  • app_ids — Array of integer IDs for applications
  • component_ids — Array of integer IDs for components (required for installed components to show values)
  • server_ids — Array of integer IDs for servers
  • server_level_ids — Array of integer IDs for server levels
  • work_task_ids — Array of integer IDs for work tasks

Special finders

  • property_values_with_holders — Array of hashes for setting property values with the following required keys:
    • value — String value of the property (required)
    • value_holder_type — String class name of allowed holders (required, can be Property, Server, ServerAspect, ServerLevel, ApplicationComponent, InstalledComponent)
    • value_holder_id — Integer ID of the value holder (required)
Success

Tip

In some cases, setting the property value from one of the value holder models might be more convenient. Installed Components, for example, have a convenience attribute, properties_with_values, that lets you set property values from the perspective of a particular installed components.

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "installed_component": { "component_name":"New Component 3", "app_name":"SR", "environment_name":"production", "properties_with_values": { "new_server_login":"admin3" } } }' http://[rails_host]/v1/installed_components?token=[api_token]
Information
Example

When you use the property_values_with_holders attribute, the model will return validation errors if any of the hash elements are missing, if the value holder type is not one of the allowed types (case sensitive), or if the value_holder_id cannot be found in the value_holder_type table. The model does not check, however, that a property has been associated with a particular application, component (required for installed components), server, or server_level. You can set those relationships using the app_ids, component_ids, server_id, and server_level_ids, attributes. Any valid object can have a property value set for it, but it will not appear in the UI for the application or Request/Step interface until the property is associated with the parent object.

Common Attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items.

Item

Associated items

properties

current_property_values, deleted_property_values, work_tasks, components, packages, server_levels, servers, apps

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 422 Unprocessable entity — Occurs when validation fails, objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<property><name>REST Property</name><find_application>SmartRelease</find_application><find_component>SS_Apache</find_component><find_environment>aws_cloud</find_environment></property>' http://[rails_host]/v1/properties?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X POST -d '{"property": {"name":"1.0.1", "find_application":"SmartRelease", "find_component":"SS_Apache", "find_environment":"aws_cloud"}}' http://[rails_host]/v1/properties/?token=[api_token]

An example of creating a property value, associating it with a component, and setting values of a known matching set of installed components:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X PUT -d '{"property": {"name":"rest_dns", "default_value":"localhost.default", "is_private":false, "component_ids":[2,3], "property_values_with_holders" : [{ "value" : "local.rest_dns", "value_holder_id" : 3, "value_holder_type" : "InstalledComponent"},{ "value" : "local.rest_dns", "value_holder_id" : 5, "value_holder_type" : "InstalledComponent"} ]} }'  http://[rails_host]/v1/properties/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X POST -d '{"property": {"name":"Rest Property 1"}, "filters": {"include_except":"work_tasks,components,server_levels"} }' https://[rails_host]/v1/properties/?token=[api_token]
Information
Recommendation

Because of the complexity of locating the components and assigning them to the property before adding property values for the installed components, BMC recommends that you create the property and assign it to the correct components, servers, and so forth and then use an UPDATE call on that created property to set the property values.

PUT /v1/properties/[id]

Updates an existing property with values from a posted document

Editable attributes

  • app_ids — Array of integer IDs for applications
  • component_ids — Array of integer IDs for components (required for installed components to show values)
  • default_value — String default value for a property
  • is_private — Boolean value for whether the display of property values should be obscured with **** (defaults to nil or false)
  • name — String name (required)
  • package_ids — Assigns a package to the property
  • server_ids — Array of integer IDs for servers
  • server_level_ids — Array of integer IDs for server levels
  • work_task_ids — Array of integer IDs for work tasks

Special Finders

  • property_values_with_holders— Array of hashes for setting property values with the following required keys:
    • value — String value of the property (required)
    • value_holder_type — String class name of allowed holders (required, can be Property, Server, ServerAspect, ServerLevel, ApplicationComponent, InstalledComponent)
    • value_holder_id — Integer ID of the value holder (required)
Success

Tip

In some cases, setting the property value from one of the value holder models might be more convenient. Installed Components, for example, have a convenience attribute, properties_with_values, that lets you set set property values from the perspective of a particular installed components.

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "installed_component": { "properties_with_values": { "new_server_login":"admin3" } } }' http://[rails_host]/v1/installed_components/[id]?token=[api_token]
Information
Example

When using the property_values_with_holders attribute, the model will return validation errors if any of the hash elements are missing, if the value holder type is not one of the allowed types (case sensitive), or if the value_holder_id cannot be found in the value_holder_type table. The model does not check, however, that a property has been associated with a particular application, component (required for installed components), server, or server_level. You can set those relationships using the app_ids, component_ids, server_id, and server_level_ids attributes. Any valid object may have a property value set for it, but it will not appear in the UI for the application or Request/Step interface until the property is associated with the parent object.

Common Attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items.

Item

Associated items

properties

current_property_values, deleted_property_values, work_tasks, components, packages, server_levels, servers, apps

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails and objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<property><name>Renamed Property</name></property>' http://[rails_host]/v1/properties/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "property": { "name" : "Renamed Property"}}'  http://[rails_host]/v1/properties/[id]?token=[api_token]

An example of finding properties for a package:

curl -H "accept: application/json" -H "Content-type: application/json" -X GET -d "{ \"filters\": { \"package_name\":\"p2\" } }" http://localhost:8080/brpm/v1/properties?token=b1413d17218e3d6369ca7527b25cc20946892dc0

An example of setting a property value with holder:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X PUT -d '{"property": {"property_values_with_holders" : [{ "value" : "local.rest2", "value_holder_id" : 3, "value_holder_type" : "InstalledComponent"},{ "value" : "local.rest2", "value_holder_id" : 2, "value_holder_type" : "InstalledComponent"} ]} }'  http://[rails_host]/v1/properties/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "property": { "name" : "Renamed Property 1"}, "filters": { "include_except": "work_tasks,components,packages" } }' https://[rails_host]/v1/properties/[id]?token=[api_token]

New in 5.0.04PUT /v1/properties/[id]/toggle_lock

Locks and unlocks property values of the component property.

Warning

Note

Only users with permission to edit Component Properties can access this API.

Required attributes

  • app_id — Integer ID of application
  • component_id — Integer ID of component of application component
  • locked — Boolean value for whether the property values should be locked or not
Warning

Note

This API only toggles the locked parameter value for component properties added on application components.

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.

  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items.

    Item

    Associated items

    properties

    current_property_values, deleted_property_values, work_tasks, components, packages, server_levels, servers, apps

An example of locking property values of the component property:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "app_id": 1, "component_id": 1, "locked": true }' https://[rails_host]/v1/properties/[id]/toggle_lock?token=[api_token]

An example of unlocking property values of the component property:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "app_id": 1, "component_id": 1, "locked": false }' https://[rails_host]/v1/properties/[id]/toggle_lock?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X PUT -d '{ "app_id": 1, "component_id": 1, "locked": true , "filters": {"include_except":"work_tasks,components,server_levels,current_property_values"}}' https://[rails_host]/v1/properties/[id]/toggle_lock?token=[api_token]

DELETE /v1/properties/[id]

Makes a property inactive. Sets the active parameter for the property to false.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X DELETE http://[rails_host]/v1/properties/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/properties/[id]?token=[api_token]

Sample output

The following JSON is a sample output from GET /v1/properties/26:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "45fc395380a559628a48a66e61b297c0"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 8d5508efe00975b2717eed48c1a09480
X-Runtime: 0.152000
Content-Type: application/json;charset=utf-8
Content-Length: 674
Date: Wed, 05 Sep 2012 18:52:52 GMT

[{
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"created_by_id": 1,
"id": 26,
"is_text": true,
"name": "Rename Sample List Again",
"updated_at": "2012-09-05T14:12:26-04:00",
"required?": false,
"list_items": [{
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"id": 181,
"last_modified_by_id": null,
"updated_at": "2012-09-05T14:12:26-04:00",
"value_num": null,
"value_text": "Renamed Sample List Item 1"
}, {
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"id": 182,
"last_modified_by_id": null,
"updated_at": "2012-09-05T14:12:26-04:00",
"value_num": null,
"value_text": "Renamed Sample List Item 2"
}]
}]

The following XML is a sample output from GET /v1/properties/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "67f3fac7087d1d6d3075cf1741dddebf"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 4b95bb6e755176bf5b5beaa01b166f57
X-Runtime: 0.541000
Content-Type: application/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Thu, 06 Sep 2012 02:08:37 GMT

<?xml version="1.0" encoding="UTF-8"?>
<property>
 <active type="boolean">true</active>
 <created-at type="datetime">2012-09-05T16:48:23-04:00</created-at>
 <default-value>localhost</default-value>
 <id type="integer">1</id>
 <is-private type="boolean">false</is-private>
 <name>Test Property 1</name>
 <updated-at type="datetime">2012-09-05T16:48:23-04:00</updated-at>
 <current-property-values type="array">
   <current-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:55:36-04:00</created-at>
     <deleted-at type="datetime" nil="true"></deleted-at>
     <id type="integer">24</id>
     <value>local.rest2</value>
     <value-holder-id type="integer">2</value-holder-id>
     <value-holder-type>InstalledComponent</value-holder-type>
   </current-property-value>
   <current-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:55:36-04:00</created-at>
     <deleted-at type="datetime" nil="true"></deleted-at>
     <id type="integer">23</id>
     <value>local.rest2</value>
     <value-holder-id type="integer">3</value-holder-id>
     <value-holder-type>InstalledComponent</value-holder-type>
   </current-property-value>
   <current-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:55:35-04:00</created-at>
     <deleted-at type="datetime" nil="true"></deleted-at>
     <id type="integer">22</id>
     <value>localhost</value>
     <value-holder-id type="integer">1</value-holder-id>
     <value-holder-type>Property</value-holder-type>
   </current-property-value>
   <current-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:33:29-04:00</created-at>
     <deleted-at type="datetime" nil="true"></deleted-at>
     <id type="integer">21</id>
     <value>local.rest</value>
     <value-holder-id type="integer">9</value-holder-id>
     <value-holder-type>InstalledComponent</value-holder-type>
   </current-property-value>
   <current-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T17:24:18-04:00</created-at>
     <deleted-at type="datetime" nil="true"></deleted-at>
     <id type="integer">5</id>
     <value>production_host</value>
     <value-holder-id type="integer">4</value-holder-id>
     <value-holder-type>InstalledComponent</value-holder-type>
   </current-property-value>
 </current-property-values>
 <deleted-property-values type="array">
   <deleted-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:33:29-04:00</created-at>
     <deleted-at type="datetime">2012-09-05T21:55:35-04:00</deleted-at>
     <id type="integer">20</id>
     <value>localhost</value>
     <value-holder-id type="integer">1</value-holder-id>
     <value-holder-type>Property</value-holder-type>
   </deleted-property-value>
   <deleted-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T21:33:13-04:00</created-at>
     <deleted-at type="datetime">2012-09-05T21:33:29-04:00</deleted-at>
     <id type="integer">19</id>
     <value>localhost</value>
     <value-holder-id type="integer">1</value-holder-id>
     <value-holder-type>Property</value-holder-type>
   </deleted-property-value>
   <deleted-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T17:24:17-04:00</created-at>
     <deleted-at type="datetime">2012-09-05T21:19:12-04:00</deleted-at>
     <id type="integer">4</id>
     <value>aws_cloud_host</value>
     <value-holder-id type="integer">3</value-holder-id>
     <value-holder-type>InstalledComponent</value-holder-type>
   </deleted-property-value>
   <deleted-property-value type="PropertyValue">
     <created-at type="datetime">2012-09-05T16:48:24-04:00</created-at>
     <deleted-at type="datetime">2012-09-05T16:50:03-04:00</deleted-at>
     <id type="integer">1</id>
     <value>localhost</value>
     <value-holder-id type="integer">1</value-holder-id>
     <value-holder-type>Property</value-holder-type>
   </deleted-property-value>
 </deleted-property-values>
 <work-tasks type="array"/>
 <components type="array">
   <component>
     <id type="integer">1</id>
     <name>AppContainer</name>
   </component>
   <component>
     <id type="integer">2</id>
     <name>SS_Apache</name>
   </component>
   <component>
     <id type="integer">3</id>
     <name>SS_Passenger</name>
   </component>
   <component>
     <id type="integer">4</id>
     <name>SS_MySQL</name>
   </component>
   <component>
     <id type="integer">5</id>
     <name>SS_RailsApp</name>
   </component>
 </components>
 <server-levels type="array">
   <server-level>
     <id type="integer">1</id>
     <name>Test Server Level</name>
   </server-level>
 </server-levels>
 <servers type="array">
   <server>
     <id type="integer">1</id>
     <name>Test Server 1</name>
   </server>
 </servers>
 <apps type="array"/>
</property>

Related topic

REST-API-version-1

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Release Process Management 5.0.08