REST apps
Apps (short for applications) are the primary software objects in BMC Release Process Management. Apps have components that are installed in multiple environments and can be deployed through process models, such as plans and requests.
GET /v1/apps
Returns all the apps.
Filters
name
— String value for the application nameactive
— Boolean value indicating active apps (default is to show only active apps)inactive
— Boolean value indicating inactive apps
Tip
To find an application by name, you can use the full name or a short code prefix 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" or "Release Process Management."
Note
This command also supports advanced filter options.
Common attributes
format
— Accept header or .xml or .json added to the last path elementtoken
— API token for authentication
Errors caused
ERROR 403 Forbidden
— Occurs when the token is invalidERROR 404 Not Found
— Occurs when no records are found
Examples
To test this method, enter this URL or your valid API key and application host into a browser or HTTP client, such as wget or curl. For example:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/apps?token=[api_token]
The following example shows filters:
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Application" } }' http://[rails_host]/v1/apps?token=[api_token]
GET /v1/apps/[id]
Returns an app by the ID.
Filters
Note
This command also supports advanced filter options.
Common attributes
id
— Unique numerical ID for a recordexport_app
— Boolean value indicating an exported JSON or XML fileNotes
- The
export_app
attribute returns an export file in the format that you are currently using in the API, either JSON or XML. For example, if a JSON header is used to request the export file, a JSON export file is returned and likewise for XML. To export an application file using theexport_app
attribute requires BMC Release Process Management version 4.6.00.01 or later. Theexport_app
attribute is the preferred method to use for both JSON and XML formats. - BMC Release Process Management version 4.6.00.01 and later releases support exporting automation scripts of types Automation and Resource Automation.
- The
export_xml
— Boolean value indicating an exported XML fileNote
BMC Release Process Management version 4.6 supports only XML for export. Version 4.6.00.01 or later supports the
export_xml
attribute; however, regardless of the format that you are currently using in the API (either JSON or XML), the exported file is always in XML format. The preferred method to use is theexport_app
attribute.optional_components
— String value for the component nameNote
Valid component names are req_templates, servers, automations, and deployment_windows. The defaults for these are false unless explicitly passed through the optional_components attribute.
format
— Accept header or .xml or .json added to the last path elementtoken
— API token for authentication
Errors caused
ERROR 403 Forbidden
— Occurs when the token is invalidERROR 404 Not found
— Occurs when the record to show is not found
Examples
To test this method, enter this URL or your valid API key and application host into a browser or HTTP client, such as wget or curl. For example:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]
The following examples show an export with no optional components:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true
curl -i -H "accept: text/xml" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_xml=true" > [application_name].xml
The following examples show an export with all optional components:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=[req_templates,servers,automations,deployment_windows]
curl -i -H "accept: application/json" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=\[req_templates, servers, automations, deployment_windows\]" > [application_name].json
The following examples show an export with only servers as optional components:
curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=[servers]
curl -i -H "accept: application/json" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=\[servers\]" > [application_name].json
POST /v1/apps
Creates a new app from a posted data.
Required attribute
name
— Unique name (string) of the appteam_ids
— Array of integer IDs for related teams
Optional attributes
active
— Boolean value (default is true)app_version
— String that represents the application versionbusiness_process_ids
— Array of integer IDs for related business processescomponent_ids
— Array of integer IDs for related componentscomponent_template_ids
— Array of integer IDs for related component templatesdefault
— Boolean value (default value is false)description
— String that describes the appenvironment_ids
— Array of integer IDs for related environmentsinstalled_component_ids
— Array of integer IDs for related installed componentspackage_template_ids
— Array of integer IDs for related package templatesrequest_ids
— Array of integer IDs for related requeststicket_ids
— Array of integer IDs for related ticketsuser_ids
— Array of integer IDs for related users
Common attributes
format
— Accept header or .xml or .json added to the last path elementtoken
— API token for authentication
Importing files
app_import team=x
— String that represents the team associated with the imported applicationNote
In BMC Release Process Management version 4.6, the
app_import
tag is the parent of the exported XML file. Exported data is inside the<app>
...</app>
tags and<app_import>
tags surround that data.In version 4.6.00.01 or later, the file type is determined automatically during the import operation for both the API and UI. However, you must specify the team for both API import formats. For example:
XML
<app_import team="[default]"> <app> … </app> </app_import>
JSON
{ "app_import": { "team": "[default]", “app”: {…} }}
Note
BMC Release Process Management version 4.6.00.01 and later releases support importing automation scripts of types Automation and Resource Automation.
Errors caused
ERROR 403 Forbidden
— Occurs when the token is invalidERROR 422 Unprocessable entity
— Occurs when validation fails; objects and errors are returned
Examples
To test this method, enter this URL or your valid API key and application host into a browser or HTTP client, such as wget or curl. For example:
curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d @[application_name].xml http://[rails_host]/v1/apps?token=[api_token]
curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<app><name>REST App</name><team_ids>2</team_ids></app>' http://[rails_host]/v1/apps?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"app" : { "name":"Rest App" } }' http://[rails_host]/v1/apps/?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"app" : { "name":"Rest App","team_ids":2 } }' http://[rails_host]/v1/apps/?token=[api_token]
The following example shows the app_import
tag:
<app_import team="[default]">
<?xml version="1.0" encoding="UTF-8"?>
<app>
<a-sorting-comps type="boolean">false</a-sorting-comps>
<a-sorting-envs type="boolean">false</a-sorting-envs>
<active type="boolean">true</active>
<app-version>0.0</app-version>
<name>import_app_blank</name>
<strict-plan-control type="boolean">false</strict-plan-control>
<components type="array"/>
<environments type="array"/>
<active-packages type="array"/>
<installed-components type="array"/>
<active-routes type="array"/>
<active-business-processes type="array"/>
<version-tags type="array"/>
<application-packages type="array"/>
<requests-for-export type="array"/>
</app>
</app_import>
The following example shows a JSON application export with the team defined and ready for import:
{"app_import":{"team":"[default]”,
"app":
"a_sorting_comps":false,
"a_sorting_envs":false,
"active":true,
"app_version":"",
"name":"EmptyApp",
"strict_plan_control":false,
"components":[],
"environments":[],
"active_packages":[],
"installed_components":[],
"active_routes":[],
"active_business_processes":[],
"version_tags":[],
"application_packages":[],
"brpm_version":"4.6.00"}
}}
PUT /v1/apps/[id]
Updates an existing app with values from a posted document.
Editable attributes
active
— Boolean value (Default is true.)app_version
— String that represents the application versionbusiness_process_ids
— Array of integer IDs for related business processescomponent_ids
— Array of integer IDs for related componentscomponent_template_ids
— Array of integer IDs for related component templatesdefault
— Boolean value (Default value is false.)description
— String that describes the appenvironment_ids
— Array of integer IDs for related environmentsinstalled_component_ids
— Array of integer IDs for related installed componentsname
— Unique name (string) of the apppackage_template_ids
— Array of integer IDs for related package templatesrequest_ids
— Array of integer IDs for related requeststeam_ids
— Array of integer IDs for related teamsticket_ids
— Array of integer IDs for related ticketsuser_ids
— Array of integer IDs for related users
Common attributes
format
— Accept header or .xml or .json added to the last path elementtoken
— API token for authentication
Errors caused
ERROR 403 Forbidden
— Occurs when the token is invalidERROR 404 Not found
— Occurs when the record to update is not foundERROR 422 Unprocessable entity
— Occurs when validation fails; objects and errors are returned
Examples
To test this method, enter this URL or your valid API key and application host into a browser or HTTP client, such as wget or curl. For example:
curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<app><name>Renamed App</name></app>' http://[rails_host]/v1/apps/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "app": { "name" : "Renamed App" } }' http://[rails_host]/v1/apps/[id]?token=[api_token]
DELETE /v1/apps/[id]
Makes an app inactive. Sets the active
parameter for the app to false.
Common attributes
id
— Unique numerical ID for a recordformat
— Accept header or .xml or .json added to the last path elementtoken
— API token for authentication
Errors caused
ERROR 403 Forbidden
— Occurs when the token is invalidERROR 404 Not found
— Occurs when no records are found
Sample output
The following JSON is sample output from GET /v1/apps
:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "eeeb7bdbbb9f3cf4b0fa00e781e6fdd1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 01f9fa0eeb3138f7920d30e7029849ad
X-Runtime: 1.759000
Content-Type: application/json;charset=utf-8
Content-Length: 6418
Date: Tue, 23 Oct 2012 13:33:59 GMT
[{
"active": true,
"app_version": "2.0.4",
"created_at": "2011-04-29T00:12:12-04:00",
"default": false,
"id": 1,
"name": "SR_|_SmartRelease",
"updated_at": "2012-09-06T08:11:35-04:00",
"requests": [{
"id": 35,
"name": "Request Example"
}],
"steps": [{
"id": 1,
"name": "Step 1"
}],
"environments": [{
"id": 1,
"name": "aws_cloud"
}, {
"id": 2,
"name": "production"
}],
"components": [{
"id": 1,
"name": "AppContainer"
}, {
"id": 2,
"name": "SS_Apache"
}, {
"id": 3,
"name": "SS_Passenger"
}, {
"id": 4,
"name": "SS_MySQL"
}, {
"id": 5,
"name": "SS_RailsApp"
}],
"installed_components": [{
"id": 7
}, {
"id": 8
}, {
"id": 9
}, {
"id": 10
}, {
"id": 1
}, {
"id": 2
}, {
"id": 5
}, {
"id": 6
}, {
"id": 3
}, {
"id": 4
}],
"teams": [],
"users": [{
"email": "admin@example.com",
"first_name": "John",
"id": 1,
"last_name": "Administrator",
"login": "admin"
}],
"tickets": []
"routes":[{
"id":3,
"name":"Another Production Route",
"route_type":"open",
"route_gates": [{
"description":null,
"id":5
}]
}, {
"id":1,
"name":"[default]",
"route_type":"open",
"route_gates": [{
"description":null,
"id":1
},{
"description":null,
"id":4
}]
}]
}]
The following XML is sample output from GET /v1/apps/1
:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ba08d21ab2b9fd1b708f87104fb3394e"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f03b6c4fe25ae6231d34ddf89579e1e9
X-Runtime: 0.857000
Content-Type: application/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 23 Oct 2012 13:38:23 GMT
<?xml version="1.0" encoding="UTF-8"?>
<app>
<active type="boolean">true</active>
<app-version>2.0.4</app-version>
<created-at type="datetime">2011-04-29T00:12:12-04:00</created-at>
<default type="boolean">false</default>
<id type="integer">1</id>
<name>SR_|_SmartRelease</name>
<updated-at type="datetime">2012-09-06T08:11:35-04:00</updated-at>
<requests type="array">
<request>
<id type="integer">1</id>
<name nil="true"></name>
</request>
</requests>
<steps type="array">
<step>
<id type="integer">1</id>
<name>Step 1</name>
</step>
</steps>
<environments type="array">
<environment>
<id type="integer">1</id>
<name>aws_cloud</name>
</environment>
<environment>
<id type="integer">2</id>
<name>production</name>
</environment>
</environments>
<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>
<installed-components type="array">
<installed-component>
<id type="integer">7</id>
</installed-component>
<installed-component>
<id type="integer">8</id>
</installed-component>
<installed-component>
<id type="integer">9</id>
</installed-component>
<installed-component>
<id type="integer">10</id>
</installed-component>
<installed-component>
<id type="integer">1</id>
</installed-component>
<installed-component>
<id type="integer">2</id>
</installed-component>
<installed-component>
<id type="integer">5</id>
</installed-component>
<installed-component>
<id type="integer">6</id>
</installed-component>
<installed-component>
<id type="integer">3</id>
</installed-component>
<installed-component>
<id type="integer">4</id>
</installed-component>
</installed-components>
<teams type="array"/>
<users type="array">
<user>
<email>admin@example.com</email>
<first-name>John</first-name>
<id type="integer">1</id>
<last-name>Administrator</last-name>
<login>admin</login>
</user>
</users>
<tickets type="array"/>
<routes type="array">
<route>
<id type="integer">3</id>
<name>Another Production Route</name>
<route-type>open</route-type>
<route-gates type="array">
<route-gate>
<description nil="true"></description>
<id type="integer">5</id>
</route-gate>
</route-gates>
</route>
<route>
<id type="integer">1</id>
<name>[default]</name>
<route-type>open</route-type>
<route-gates type="array">
<route-gate>
<description nil="true"></description>
<id type="integer">1</id>
</route-gate>
<route-gate>
<description nil="true"></description>
<id type="integer">4</id>
</route-gate>
</route-gates>
</route>
</routes>
</app>
Comments
Log in or register to comment.