Bundles and Promotion Web Services
Overview
Universal Controller supports the following RESTful-based web services for Bundles and Promotion operations, which are listed alphabetically on this page under two categories:
Bundles
Promotion
- Bundleless Promotion
- Cancel a Scheduled Bundle Promotion
- Delete a Scheduled Bundle Promotion
- Promote a Bundle or Schedule a Bundle Promotion
- Modify a Promotion Target
- List Promotion Targets
- Delete a Promotion Target
- Read a Promotion Target
- Refresh Target Agents
Formatting specifications for each web service, including details about parameter requirements, are provided.
Bundles
Bundle Report
Description | |
---|---|
URI | http://host_name/uc/resources/bundle/report |
HTTP Method | GET |
Description | Retrieve Bundle Report details using specific query parameters. |
Example URI | |
URI Parameters | See Bundle Report: URI Parameters, below. |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See Bundle Report: Example Response, below. |
Properties | See Bundle Properties. |
Bundle Report: URI Parameters
Parameter | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| UUID | ID used within the Controller to identify this Bundle. | String value of the bundle sysId. | Y |
|
| Bundle Name | Name used within the Controller to identify this Bundle. | String value of the bundle name. | Y |
|
Bundle Report: Example Response
XML Response | JSON Response |
---|---|
Create a Bundle
Description | |
---|---|
URI | http://host_name/uc/resources/bundle |
HTTP Method | POST |
Description | Creates a Bundle. |
Example URI | http://localhost:8080/uc/resources/bundle |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Create a Bundle: Example Request, below. |
Properties | See Bundle Properties. |
Example Response |
|
Create a Bundle: Example Request
XML Request | JSON Request |
---|---|
Bundle Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Agent Clusters | Task Items to include | String value of task | N |
| Applications | Applications to include | String value of Applications | N |
| Business Services | Business Services Items to include | String value of Business Services | N |
| Calendars | Calendars Items to include | String value of Calendars | N |
| Credentials | Agent Clusters Items to include | String value of Agent Clusters | N |
| Custom Days | Custom Days Items to include | String value of Custom Days | N |
| Database Connections | Database Connections Items to include | String value of Database Connections | N |
| Email Connections | Email Connections Items to include | String value of Email Connections | N |
| Email Templates | Email Templates Items to include | String value of Email Templates | N |
| PeopleSoft Connections | PeopleSoft Connections Items to include | String value of PeopleSoft Connections | N |
| Sap Connections | Sap Connections Items to include | String value of Sap Connections | N |
| Scripts | Scripts Items to include | String value of Scripts | N |
| SNMP Managers | SNMP Managers Items to include | String value of SNMP Managers | N |
| Tasks | Task Items to include | String value of task | N |
| Triggers | Triggers Items to include | String value of Triggers | N |
| Universal Templates | Universal Templates Items to include | String value of Universal Templates | N |
| Variables | Variables Items to include | String value of Variables | N |
| Virtual Resources | Virtual Resources Items to include | String value of Virtual Resources | N |
| Default Promotion Target | Promotion Target server name | String value of target | N |
| Description | Bundle description | String value of description | N |
| Exclude On Existence | Exclude Items on existence | String value | N |
| n/a | Universal Controller release that the record was exported from. | read only | N |
| n/a | Record table information. | read only | N |
| Follow References | Follow references items | Boolean value | N |
| Bundle Name | Bundle name | String value of the bundle name | Y |
| Member Of Business Services | List of Business Services that this task belongs to | String value | N |
| Promote Bundle Definition | Promote Bundle Definition | Boolean value | N |
| Promote Member of Business Service | Promote List of Business Services that this task belongs to | String value | N |
| n/a | System ID field in the database for this Bundles record. | Persisted only if retainSysIds is set to true. | N |
| Visible To | Visible to user | String value of user name | N |
Create a Bundle By Business Services
Description | |
---|---|
URI | |
HTTP Method | POST |
Description | Creates a Bundle. |
Example URI | |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Create a Bundle By Business Services: Example Request, below. |
Properties | |
Example Response |
|
Create a Bundle By Business Services: Example Request
XML Request | JSON Request |
---|---|
Create a Bundle By Business Services Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Bundle Name | Bundle name | String value of the bundle name. | Y |
| Types To Include | Include item types | String value. | Y |
| Member Of Business Services | List of Business Services that this bundle belongs to | String value of the list. | N |
| Business Services To Include | Include List of Business Services for this bundle creation | String value of the list. | Y |
Create a Bundle By Date
Description | |
---|---|
URI | |
HTTP Method | POST |
Description | Creates a Bundle. |
Example URI | |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Create a Bundle By Date: Example Request, below. |
Properties | |
Example Response |
|
Create a Bundle By Date: Example Request
XML Request | JSON Request |
---|---|
Create a Bundle By Date Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Bundle Name | Bundle name | String value of the bundle name. | Y |
| Types To Include | Include item types | String value. | Y |
| Member Of Business Services | List of Business Services that this bundle belongs to | String value of the list. | N |
| Business Services To Include | Include List of items created On/After the dae | String value of the date. | Y |
Delete a Bundle
Description | |
---|---|
URI | http://host_name/uc/resources/bundle |
HTTP Method | DELETE |
Description | Deletes a Bundle. |
URI Parameters | See Delete a Bundle: URI Parameters, below. |
Example URI | |
Example Response |
|
Delete a Bundle: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Bundle. | String value of the bundle sysId. | Y |
|
| Name used within the Controller to identify this Bundle. | String value of the bundle name. | Y |
|
List Bundles
Description | |
---|---|
URI | http://host_name/uc/resources/bundle/list |
HTTP Method | GET |
Description | Retrieves information on all Bundles. |
Example URI | |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See List Bundles: Example Response, below. |
Properties | See Bundle Properties. |
List Bundles Request Parameters
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| n/a | Request parameter bundlename. | String value of the bundle name. Wildcards are supported. | N |
| n/a | Request parameter businessServices. | String value of the bundle business service. | N |
| n/a | Request parameter defaultPromotionTarget. | String value of the promotion target. Wildcards are supported. | N |
List Bundles: Example Response
XML Response | JSON Response |
---|---|
Modify a Bundle
Description | |
---|---|
URI | http://host_name/uc/resources/bundle |
HTTP Method | PUT |
Description | Modifies the Credential specified by the |
Example URI | http://localhost:8080/uc/resources/bundle |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Modify a Bundle: Example Request, below. |
Properties | See Bundle Properties. |
Example Response |
|
Modify a Bundle: Example Request
XML Request | JSON Request |
---|---|
Read a Bundle
URI | http://host_name/uc/resources/bundle |
HTTP Method | GET |
Description | Retrieve Bundle details using a specific query parameters. |
URI Parameters | See Read a Bundle: URI Parameters, below. |
Example URI | |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See Read a Bundle: Example Response, below. |
Properties | See Bundle Properties. |
Read a Bundle: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Bundle. | String value of the bundle sysId. | Y |
|
| Name used within the Controller to identify this Bundle. | String value of the bundle name. | Y |
|
Read a Bundle: Example Response
The exportReleaseLevel
and exportTable
properties are specified as attributes in XML.
XML Response | JSON Response |
---|---|
Promotion
Bundleless Promotion
Description | |
---|---|
URI | http://host_name/uc/resources/promote |
HTTP Method | POST |
Description | Promotes, without a bundle, one or more items of a specific type. |
Example URI | http://localhost:8080/uc/resources/promote |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | application/xml, application/json |
Example Request | |
Request Properties | See Promote: Properties. |
Example Response |
Bundleless Promotion: XML and JSON Examples
Examples | XML | JSON |
---|---|---|
Example Request | ||
Example Response |
Bundleless Promotion: Properties
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
itemType | n/a | Item type for promotion item(s). | Valid Values: One of the following (not case sensitive):
| Y | |
itemIds | n/a | IDs for promotion items. | Comma-separated list of promotion item IDs. | Y (unless itemNames is specified) | itemNames |
itemNames | n/a | Names for promotion items. | Comma-separated list of promotion item names. | Y (unless itemIds is specified) | itemIds |
promotionTargetId | n/a | ID of the Promotion Target. | Y (unless promotionTargetName is specified) | promotionTargetName | |
promotionTargetName | Promotion Target | Name of the Promotion Target. | Y (unless promotionTargetId is specified) | promotionTargetId | |
overrideUser | User | User name to use instead of the default User name for the Promotion Target. | Y (if overridePassword is specified) | ||
overridePassword | Password | User password to use instead of the default User password for the Promotion Target. | Y (if overrideUser is specified) | ||
excludeOnExistence | Exclude On Existence | Item types that will not be updated if they exist on the target server. | Comma-separated list of excluded types. Valid Values:
| N | |
followReferences | Follow References | Dynamically include items in the promotion that are referenced by promotion items. | Valid values:
| N | |
allUnvTmpltChanges | Allow Universal Template Changes | Allow the promotion to contain new or changed Universal Templates. | Valid values:
Note In order to promote Universal Template changes, the user must have the ops_universal_template_admin role or the ops_admin role. | N |
Cancel a Scheduled Bundle Promotion
Description | ||
---|---|---|
URI | ||
HTTP Method | POST | |
Description | Cancels the scheduled promotion of a Bundle. | |
URI Parameters | See Cancel a Scheduled Bundle Promotion: URI Parameters, below. | |
Consumes Content-Type | n/a | |
Produces Content-Type | application/xml, application/json | |
Example URI |
| |
Example Response | See Cancel a Scheduled Bundle Promotion: XML and JSON Examples. |
Cancel a Scheduled Bundle Promotion: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| UUID of the promotion schedule. | N |
| |
| Name of the bundle. | N |
| |
| UUID of the bundle. | N |
| |
| Date when the promotion was scheduled. | Format: yyyy-MM-dd (For example: 2018-11-14). | Y | |
| Time when the promotion was scheduled. | Format: HH:mm (For example: 22:00). | Y |
Cancel a Scheduled Bundle Promotion: XML and JSON Examples
Examples | XML | JSON |
---|---|---|
Example Response |
Delete a Scheduled Bundle Promotion
Description | |
---|---|
URI | http://host_name/uc/resources/promotion/schedule |
HTTP Method | DELETE |
Description | Deleted the scheduled promotion of a Bundle. |
URI Parameters | See Delete a Scheduled Bundle Promotion: URI Parameters, below. |
Example URI |
|
Example Response |
|
Delete a Scheduled Bundle Promotion: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| UUID of the promotion schedule. | N |
| |
| Name of the bundle. | N |
| |
| UUID of the bundle. | N |
| |
| Date when the promotion was scheduled. | Format: yyyy-MM-dd (For example: 2018-11-14). | Y | |
| Time when the promotion was scheduled. | Format: HH:mm (For example: 22:00). | Y |
Promote a Bundle or Schedule a Bundle Promotion
Description | |
---|---|
URI | http://host_name/uc/resources/bundle/promote |
HTTP Method | POST |
Description | Promote a Bundle or schedule the promotion of a Bundle. |
Example URI | http://localhost:8080/uc/resources/bundle/promote |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | application/xml, application/json |
Example Request | |
Request Properties | |
Example Response |
Promote a Bundle or Schedule a Bundle Promotion: XML and JSON Examples
Examples | XML | JSON |
---|---|---|
Example Request | ||
Example Response |
Promote a Bundle or Schedule a Bundle Promotion: Properties
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| Allow Universal Template Changes | Allow the promotion to contain new or changed Universal Templates. | Valid values:
Note In order to promote Universal Template changes, the user must have the ops_universal_template_admin role or the ops_admin role. | N | |
| Create Snapshot | Schedule the Bundle promotion using the current Bundle records. | Valid values:
| N | |
| Date | Date on which to promote the Bundle. | Y | ||
| n/a | 32-character sysid of the Bundle to be promoted. | Y |
| |
| Bundle Name | Name of the Bundle to be promoted. | Y |
| |
| System Notification | System Notification to send on success and/or failure of the promotion. | Valid values (not case sensitive):
| N | |
| Password | User password to use instead of the default User password for the promotion target. | Y | ||
| User | User name to use instead of the default User name for the promotion target. | Y | ||
| n/a | ID of the Controller cluster node on which to promote the Bundle. | Default is the Default Promotion Target of the specified Bundle. | N |
|
| Promotion Target | Name of the Controller cluster node on which to promote the Bundle. | Default is the Default Promotion Target of the specified Bundle. | N |
|
| Schedule | Indication of whether or not to schedule a Bundle promotion. | Valid values
| Y | |
| Time | Time on which to promote the Bundle. | Default is 00:00. | N |
Create a Promotion Target
Description | |
---|---|
URI | |
HTTP Method | POST |
Description | Creates a Promotion Target. |
Example URI | http://localhost:8080/uc/resources/promotiontarget |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Create a Promotion Target: Example Request, below. |
Properties | |
Example Response |
|
Create a Promotion Target: Example Request
Note
All of the mapping agents will be automatically mapped when you execute the Refresh Target Agent command, so the mapping agents included in the request will be ignored.
Examples | XML | JSON |
---|---|---|
Example Request |
Promotion Target Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| n/a | List of agentMapping details associated with the Controller | agentMapping details | N |
| Description | Promotion Target description | String value of description | N |
| n/a | Universal Controller release that the record was exported from. | read only | N |
| n/a | Record table information. | read only | N |
| Name | Name for this Promotion Target. | String value of the promotion target name | Y |
| Member Of Business Services | List of Business Services that this task belongs to | String value | N |
| Password | Login password on the target cluster node of Universal Controller. | String value of password | N |
| n/a | Specification for whether or not the Create a Promotion Target web service will persist the sysId property.
Note In XML web services, | Valid values: true/false (default is true). | N |
| Source Agent | List of source agent names. | List of source agent names. | N |
| n/a | System ID field in the database for this Prommotion Target record. | Persisted only if retainSysIds is set to true. | N |
| Target Agent | Target agent name. | String value of the target agent name. | Y |
| Type | Agent type. | String value of agent type. (For example, Windows) | Y |
| URI | Uniform Resource Identifier (URI) used to locate the Promotion Target cluster node. | String value uri. | Y |
| User | Login ID on the target cluster node of Universal Controller. | String value of user. | N |
Modify a Promotion Target
Modify a Promotion Target is used for updating the promotion target details and source agent details of the mapping agent details.
You can map multiple source agents to a specific target agent, but you cannot add the same source agents for more than one target agent.
Description | |
---|---|
URI | |
HTTP Method | PUT |
Description | Updates a Promotion Target. |
Example URI | http://localhost:8080/uc/resources/promotiontarget |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Modify a Promoition Target: Example Request, below. |
Properties | |
Example Response |
|
Modify a Promotion Target: Example Request
Examples | XML | JSON |
---|---|---|
Example Request |
List Promotion Targets
List Promotion Targets allows the retrieval of promotion target details based on provided search criteria.
Description | |
---|---|
URI | |
HTTP Method | GET |
Description | Retrieve Promotion Target details. |
URI Parameters | See List Promotion Targets: URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/promotiontarget/list?targetname=test http://localhost:8080/uc/resources/promotiontarget/list?targetname=* http://localhost:8080/uc/resources/promotiontarget/list?targetname=local&businessServies=bus-1,bus-2 |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Respone | See List Promoition Targets: Example Response, below. |
Response Properties |
List Promotion Targets: URI Parameters
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| N/A | Request parameter targetname | String value of the target name. Wildcards are supported. | N |
| N/A | Request parameter businessServices. | String value of the business service | N |
List Promotion Targets: Example Response
The exportReleaseLevel
and exportTable
properties are specified as attributes in XML.
Examples | XML | JSON |
---|---|---|
Example Response |
Delete a Promotion Target
Delete a Promotion Target allows the deletion of a specified promotion target.
Description | |
---|---|
URI | |
HTTP Method | DELETE |
Description | Delete a specified Promotion Target. |
URI Parameters | See Delete a Promotion Target: URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/promotiontarget?targetname=test http://localhost:8080/uc/resources/promotiontarget?targetid=ed76d6c78f06402d882e155bfd42b98f |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | text/plain |
Properties | |
Example Response |
|
Delete Promotion Target: URI Parameters
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive |
---|---|---|---|---|---|
| n/a | Request parameter targetname. | String value of the promotion target name | Y |
|
| n/a | Request parameter targetid. | String value of the promotion target sysId | Y (unless targetname is specified) |
|
Read a Promotion Target
Read a Promotion Target allows the reading of promotion target details based on a specified targetid or targetname.
Description | |
---|---|
URI | |
HTTP Method | GET |
Description | Retrieve a specified Promotion Target details. |
URI Parameters | See Read a Promotion Target: URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/promotiontarget?targetname=test http://localhost:8080/uc/resources/promotiontarget?targetid=ed76d6c78f06402d882e155bfd42b98f |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See Read a Promoition Target: Example Response, below. |
Response Properties |
Read a Promotion Target: URI Parameters
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive |
---|---|---|---|---|---|
| n/a | Request parameter targetname. | String value of the promotion target name | Y |
|
| n/a | Request parameter targetid. | String value of the promotion target sysId | Y (unless targetname is specified) |
|
Read a Promotion Target: Example Response
The exportReleaseLevel
and exportTable
properties are specified as attributes in XML.
Examples | XML | JSON |
---|---|---|
Example Request |
Refresh Target Agents
Refresh Promotion Target Agents allows the refreshing of the target Controller agents mapped to the promotion target.
Description | |
---|---|
URI | |
HTTP Method | POST |
Description | Refresh the target agents for a specified Promotion Target. |
URI Parameters | See Refresh Target Agents: URI Parameters, below. |
Example URI | |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | Successfully refreshed target agents for test-1 |
Refresh Target Agents: URI Parameters
Property | Description | Specifications | Required | Mutually Exclusive |
---|---|---|---|---|
| Name for this Promotion Target. | String value of the promotion target name passed as query parameter. | Y |
|
| Promotion Target sysId. | String value of the promotion target sysId passed as query parameter. | Y (unless targetname is specified) |
|
| Override Login ID on the target cluster node of Universal Controller. | String value of user, passed as request body. | N | |
| Override Login password on the target cluster node of Universal Controller. | String value of password, passed as request body. | N |
Refresh Target Agents: Example Request
Examples | XML | JSON |
---|---|---|
Example Request |