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

Note

The include_except and alone filters are available in only 5.0.03.004 and later versions of RPM. Use these filters to limit the data in API response and hence, reduce the API response time.

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 component
server_group_name—String value of the application name associated with an installed component

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. See the table below for the items and their associated items.

Item	Associated items
installed_components	application_component, application_environment

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".

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]

Filter examples:

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]

curl -i -H "accept: application/json" -H "Content-type: application/json" -d '{ "filters": { "include_except":"application_component" }}' -X GET https://[rails_host]/v1/installed_components?token=[api_token]

GET /v1/installed_components/[id]

Returns an installed component 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. See the table below for the items and their associated items.

Item	Associated items
installed_components	application_component, application_environment, associated_property_values, steps version_tags, servers, server_group, server_aspect_groups, server_aspects_through_groups

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

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

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]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"application_component, version_tags" }}' https://[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

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. See the table below for the items and their associated items.

Item	Associated items
installed_components	application_component, application_environment, associated_property_values, steps, version_tags servers, server_group, server_aspect_groups, server_aspects_through_groups

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 POST -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]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "installed_component": { "component_name":"SS_Apache", "app_name":"RestApp", "environment_name":"production" }, "filters": {"include_except" : "application_component, version_tags"}}' https://[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

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. See the table below for the items and their associated items.

Item	Associated items
installed_components	application_component, application_environment

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

NEW IN 5.0.03.001Response attributes

Installed component ID — Contains the ID of the installed component
Application component ID— Contains the ID of the application component
Application environment ID— Contains the ID of the application environment
Updated at— Timestamp when the installed component is updated

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]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "installed_component": { "component_name":"SS_Apache", "app_name":"RestApp", "environment_name":"production" }, "filters": { "include_except":"application_component, version_tags" }}' https://[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.

NEW IN 5.0.03.001 If successful, the response does not contain any data.

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>

NEW IN 5.0.03.001The following XML is a sample output from PUT /v1/installed_components/12:

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
Cache-Control: no-cache
X-Request-Id: 6a7204c15e9c9126669659db36e333ae
X-Runtime: 12.243000
Vary: Origin
Referrer-Policy: origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: DENY
X-Permitted-Cross-Domain-Policies: none
X-XSS-Protection: 1; mode=block
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 03 Apr 2018 10:31:46 GMT


{  
   "id":11,
   "location":null,
   "reference_id":null,
   "version":null,
   "application_component":{  
      "id":6,
      "updated_at":"2017-09-10T14:29:38+05:30"
   },
   "application_environment":{  
      "id":4,
      "updated_at":"2017-09-10T14:29:29+05:30"
   }
}

Page tree

GET /v1/installed_components

Filters

Common attributes

Errors caused

Examples

GET /v1/installed_components/[id]

Common attributes

Filters

Errors caused

Additional parameters

POST /v1/installed_components

Required attributes

Optional Finder Methods

Special property setter

Optional attributes

Common attributes

Filters

Errors caused

Examples

PUT /v1/installed_components/[id]

Finder methods

Special property setter

Optional attributes

Common attributes

Filters

Errors caused

NEW IN 5.0.03.001Response attributes

Examples

DELETE /v1/installed_components/[id]

Common attributes

Errors caused

Examples

Sample output

Related topic

Page tree

REST installed components

GET /v1/installed_components

Filters

Common attributes

Errors caused

Examples

GET /v1/installed_components/[id]

Common attributes

Filters

Errors caused

Additional parameters

POST /v1/installed_components

Required attributes

Optional Finder Methods

Special property setter

Optional attributes

Common attributes

Filters

Errors caused

Examples

PUT /v1/installed_components/[id]

Finder methods

Special property setter

Optional attributes

Common attributes

Filters

Errors caused

NEW IN 5.0.03.001Response attributes

Examples

DELETE /v1/installed_components/[id]

Common attributes

Errors caused

Examples

Sample output

Related topic