Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST installed components

An installed component is an instance of a component that is unique to an environment and an application.

GET /v1/installed_components

Returns all installed components.

Filters

  • app_id — Integer value of the application ID
  • app_name — String value of the application associated with an installed component
  • component_id — Integer value of the component ID
  • component_name — String value of the component name
  • environment_id — Integer value of the environment ID
  • environment_name — String value of the application name associated with an installed compnent
  • server_group_name — String value of the application name associated with an installed component

Tip

To find an application by name, you can use the full name or a short code prefix if that prefix is separated from the main name by a delimiter '|'. If the application name is "BMC Release Process Management", a name with a short code might be "BRPM_|_Release Process Management." To find this application, the value for "name" could be either "BRPM" and "Release Process Management".

This command also supports advanced filter options.

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/installed_components?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/installed_components?token=[api_token]

An example of a filter:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "app_name":"BRPM", "component_name":"SS_Apache", "environment_name":"aws_cloud" }}'   http://[rails_host]/v1/installed_components?token=[api_token]

GET /v1/installed_components/[id]

Returns an installed component by ID.

Filters

This command also supports advanced filter options.

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 record to show is not found

Additional parameters

Starting with BMC Release Process Management version 4.4.00.04 and later, the following additional parameters are added to an installed component:

  • current_associated_property_values — lists properties with their ID's, names, and only values that are currently used for the installed component
  • associated_property_values — lists properties with their ID's, names, and all values that are were used for the installed component

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/installed_components/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/installed_components/[id]?token=[api_token]

POST /v1/installed_components

Creates a new installed component from posted data

Required attributes

  • app_name — String name of the application
  • component_name — String name of the parent component object
  • environment_name — String name of the environment object

Tip

Creating a valid installed component requires at least the following finder methods that look up and, if the installed component is found, link this installed component to the named component, application, and environment. All three are required. If you know the application_component_id and the application_environment_id from some other operation, you can set those values as shown instead of using these finders. In that case, both of those IDs are required.

  • application_component_id — Integer ID of application component model (see special finders to avoid creating this object manually)
  • application_environment_id — Integer ID of application_environment model (see special finders to avoid creating this object manually)

Tips

  • Attributes for the application_component_id and the application_environment_id are available but typically remain unused because of the convenience of the name—based finders for component_name, app_name, and environment_name.
  • If you use the | delimiter in the application name, you can search the app_name field by using a prefix. For example, searching for RLM will find installed components associated with RLM_|_BMC Release Lifecycle Management.

Optional Finder Methods

  • server_names — String or array of string names of the servers
  • server_aspect_names — String or array of string names of the server aspects
  • server_aspect_group_names — String or array of string names of the server aspect groups
  • server_group_name — String name of the single associated server group (through default server group ID)

Special property setter

  • properties_with_values — Hash of key value pairs, such as "{ 'server_url' : 'localhost', 'user_name' : 'admin' }"

Notes

  • The property must already exist and must already be assigned to the component.
  • The properties_with_values setter is supported only for the JSON format.

Optional attributes

  • default_server_group_id — Integer ID of the default server group
  • location — String field storing the physical or virtual location of the installed component
  • version — String field showing the current version of the installed component
  • reference_id — Integer field linking the installed component to another installed component

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 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 POST -d '<installed_component> <app_name>SmartRelease</app_name> <component_name>SS_Apache2</component_name> <environment_name>production</environment_name> </installed_component>'
http://[rails_host]/v1/installed_components?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "installed_component": { "component_name":"New Component 3", "app_name":"SR", "environment_name":"production" } }' http://[rails_host]/v1/installed_components/?token=[api_token]

Example of setting a property value on creation:

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]

PUT /v1/installed_components/[id]

Updates an existing installed component with values from a posted document

Finder methods

  • app_name — String name of the application
  • component_name — String name of the parent component object
  • environment_name — String name of the environment object

Tip

Creating a valid installed component requires at least the following finder methods that look up and, if the installed component is found, link this installed component to the named component, application, and environment. All three are required. If you know the application_component_id and the application_environment_id from some other operation, you can set those values as shown instead of using these finders. In that case, both of those IDs are required.

  • application_component_id — Integer ID of application component model (see special finders to avoid creating this object manually)
  • application_environment_id — Integer ID of application_environment model (see special finders to avoid creating this object manually)

Tips

  • Attributes for the application_component_id and the application_environment_id are available but typically remain unused because of the convenience of the name-based finders for component_name, app_name, and environment_name.
  • If you use the | delimiter in the application name, you can search the app_name field by using a prefix. For example, searching for RLM will find installed components associated with RLM_|_BMC Release Lifecycle Management.
  • server_names — String or array of string names of the servers
  • server_aspect_names — String or array of string names of the server aspects
  • server_aspect_group_names —String or array of string names of the server aspect groups
  • server_group_name — String name of the single associated server group (through default server group ID)

Special property setter

  • properties_with_values — Hash of key value pairs such as "{ 'server_url' : 'localhost', 'user_name' : 'admin' }"

Notes

  • The property must already exist and must already be assigned to the component.
  • The properties_with_values setter is supported only for the JSON format.

Optional attributes

  • default_server_group_id — Integer ID of the default server group
  • location — String field storing the physical or virtual location of the installed component
  • version — String field showing the current version of the installed component
  • reference_id — Integer field linking the installed component to another installed component

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 record to update is not found
  • 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 PUT -d '<installed_component><name>Renamed Installed Component</name></installed_component>' http://[rails_host]/v1/installed_components/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "installed_component": { "name" : "Renamed Installed Component"}}'  http://[rails_host]/v1/installed_components/[id]?token=[api_token]

Example of setting a property value for an existing installed component:

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]

DELETE /v1/installed_components/[id]

Makes an installed component inactive. Sets the active parameter for the installed component 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/installed_components/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/installed_components/[id]?token=[api_token]

Sample output

The following JSON is a sample output from GET /v1/installed_components/12:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "f13c3aba0bb381129d453c401598d8cd"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c78a824a4f563093c415866e95c5734a
X-Runtime: 0.774000
Content-Type: application/json;charset=utf-8
Content-Length: 6998
Date: Tue, 23 Oct 2012 19:11:06 GMT

{
   "id": 12,
   "location": null,
   "reference_id": null,
   "version": null,
   "current_associated_property_values": [
        {
           "id": 5,
           "value": "1_new",
           "name": "prop 1"
        }
   ],
   "application_component": {
       "id": 7,
       "updated_at": "2014-05-16T09:16:28-04:00",
        "app": {
            "app_version": "1.0",
            "id": 2,
            "name": "app1"
        },
        "component": {
            "id": 2,
            "name": "SS_Apache"
        }
    },
    "application_environment": {
        "id": 4,
        "updated_at": "2014-05-16T09:16:14-04:00",
        "environment": {
            "id": 2,
            "name": "production"
        }
    },
    "associated_property_values": [
        {
           "id": 5,
           "value": "1_new",
           "name": "prop 1"
        },
        {
           "id": 2,
           "value": "1",
           "name": "prop 1"
        }
   ],
    "steps": [],
    "version_tags": [],
    "servers": [],
    "server_aspect_groups": [],
    "server_aspects_through_groups": []
}

The following XML is a sample output from GET /v1/installed_components/12:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "707c21d9d2a2800d95f5656ef03734ac"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f690345c419eee9ee0b6ffec577ecda0
X-Runtime: 0.652000
Content-Type: application/xml;charset=utf-8
Content-Length: 1140
Date: Tue, 23 Oct 2012 19:12:54 GMT

<?xml version="1.0" encoding="UTF-8"?>
<installed-component>
 <id type="integer">12</id>
 <location nil="true"/>
 <reference-id type="integer" nil="true"/>
 <version nil="true"/>
 <current-associated-property-values type="array">
   <current-associated-property-value>
     <id>5</id>
     <value>1_new</value>
     <name>prop 1</name>
   </current-associated-property-value>
   <current-associated-property-value>
     <id type="integer">2</id>
     <value>1</value>
     <name>prop 1</name>
   </current-associated-property-value>
 </current-associated-property-values>
 <application-component>
   <id type="integer">7</id>
   <updated-at type="datetime">2014-05-16T09:16:28-04:00</updated-at>
   <app>
     <app-version>1.0</app-version>
     <id type="integer">2</id>
     <name>app1</name>
   </app>
   <component>
     <id type="integer">2</id>
     <name>SS_Apache</name>
   </component>
 </application-component>
 <application-environment>
   <id type="integer">4</id>
   <updated-at type="datetime">2014-05-16T09:16:14-04:00</updated-at>
   <environment>
     <id type="integer">2</id>
     <name>production</name>
   </environment>
 </application-environment>
 <associated-property-values type="array">
   <associated-property-value type="PropertyValue">
     <id type="integer">14</id>
     <value>test</value>
     <name>prop 2</name>
   </associated-property-value>
 </associated-property-values>
 <steps type="array"/>
 <version-tags type="array"/>
 <servers type="array"/>
 <server-aspect-groups type="array"/>
 <server-aspects-through-groups type="array"/>
</installed-component>

Related topic

REST-API-commands

 

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