この製品のドキュメントセットは、偏向のない言語を使用するように配慮されています。このドキュメントセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブ ランゲージの取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
This chapter documents the use of web services for Service Catalog. These include web services which implement the SOAP-based version of Requisition API (RAPI 2), an API which allows an external system to create and manage service requests within Service Catalog. The web services include additional requests, to allow the management of delivery and authorization tasks within a service request; and to review the contents of the Service Catalog.
where elements enclosed in angle brackets (<>) indicate that an appropriate parameter or parameter value must be substituted.
nsAPI supports a variety of filters for GET operations based on the entity type:
For POST operations, the following filters are supported:
For wildcard search in entity name filters (for example, ?name=<value>), leading wildcard characters such as “*” or “%” in the search string are ignored. If these characters are located in the middle or at the end of the string, they are applied in wildcard matching.
To enable the use of a leading wildcard character in name search, locate the property ContainsQueryInFnS
in the newscale.properties file (under RequestCenter.war/WEB-INF/classes/config) and set the value to true:
Note Such search operations may negatively impact system performance and are generally not recommended in production environments.
Associated entities are nested entities that are fetched in conjunction with the primary entity —for example, the OU of which a person is a member. Associated entity name filters do not support wildcard search. Searches on those filters return only results with an exact match, and are case-sensitive. In other words, wildcard characters in the search string are treated as literals during matching. For example,
returns people in the organization unit literally named “star*OU”.
Sorting controls are available for operations that return more than one row of data. As with filters, sorting controls are specified as parameters in the REST URL:
When no sorting parameter is passed in the REST URL, the default sort field and sort order are assumed, as shown in the table below.
|
|
Row Id is the physical order in which the records are inserted into the service item, standard and custom content tables. This corresponds to the column named PrimaryID in those tables.
Service Items, Standards and Custom Content entities support sorting for all columns. Other entities support sorting for specific fields only. For more information, see API Reference and Examples.
returns person records listed in ascending order by their last name.
returns person records listed in descending order by their login name.
Paging controls are available for operations that return more than one row of data. They are also specified as parameters in the REST URL:
The above parameters and the total number of records returned are shown as attributes in the root tag of the REST XML response, as shown in the example below:
If you specify a startRow greater than the number of records which would be retrieved, an HTTP 500 error is returned. If you specify a recordSize greater than the number of records which would be retrieved, all rows are returned.
In the following examples, assume there are 60 services defined in Service Designer and the maximum number of records specified for the nsAPI setting in Portal Designer is 30.
returns the first 30 services. Here is the how the response would look like for such a request:
returns 30 services, starting from the fourth one. Here is the how the response would look like for such a request:
returns 5 services, starting from the fourth one. Here is the how the response would look like for such a request:
returns 30 services, starting from the fourth one. Here is the how the response would look like for such a request:
Certain entities contain a nested structure. The retrieval of only the first-level children or associated entities are supported by nsAPI. Parent entities and their child entities are summarized in the table.
For category, service or person searches that return more than one row of data in the result set, the associated entities are not fetched for performance reasons. The associated entities are available only in GET by Id or Name operations on the individual entities.
returns the groups of which the person is a member:
returns the groups to which the person belongs.
does not return the groups the person belongs to.
nsAPI calls can be invoked in JavaScript portlets developed on the Portal Designer module. Using JavaScript, REST URL, AJAX, or Ext JS components, a portlet can be created to retrieve the data for the desired entities and rendered in a grid format.
Here is an example of using Ext JS to render a list of categories:
Namespace variables for the currently logged-in user are available to be used in the JavaScript portlet; for example:
When accessed through JSR portlets, the nsAPI Java client can be used to invoke the login and logout operations.
Here is an example of Spring-based JSR Portlet Controller to get the details of the logged-in user:
Here are some sample code snippets that illustrate the methods for fetching entities. For further details on these methods, see the Javadoc for the individual entity classes.
Here are some sample code snippets that illustrate the methods for creating/updating a person and taking actions on tasks. For further details on these methods, see the Javadoc for the individual entity classes.
The javadoc for nsAPI can be located in the Image folder of the product installer. Examples for invoking the nsAPI through REST URL and Java client are provided for each of the supported entities.
|
|
---|---|
Get policies by service item type. Returns policies by Service Item Type Name. /RequestCenter/nsapi/serviceitem/definition/{ serviceItemTypeName }/policies <policies totalCount="2" startRow="1" recordSize="2"> <policy policyType="quota" accountName="bangalore" policyEnabled="true" executionOrder="2" dataTypeLogicName="SiLaptop" policyTemplateLogicName="quotacheck" policyId="34" name="Laptop Quota policy"> <paramValue policyParamLogicName="quotacheck-serviceitemattribute" paramValue="Quota"/> <paramValue policyParamLogicName="quotacheck-quotathreshold" paramValue="90"/> <policyAction policyActionTemplateName="orderservice" executionOrder="1"> <actionParamValue policyActionTemplateParamLogicName="orderservice-servicename" actionParamValue="Apple iPhone"/> <actionParamValue policyActionTemplateParamLogicName="orderservice-initiatorname" actionParamValue="admin"/> policyActionTemplateParamLogicName="orderservice-customername" actionParamValue="admin"/> <actionParamValue policyActionTemplateParamLogicName="orderservice-billtoOU" actionParamValue="Site Administration"/> |
|
policyActionTemplateParamLogicName="orderservice-sections"> <dictionary name="TabletComputerDict"> <policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> <actionParamValue policyActionTemplateParamLogicName="errormessage" actionParamValue="Policy alert when Price is updated for a Laptop"/> |
|
/RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName }/policies/id/{policyId} |
|
Returns a polices by serviceItemTypeName, policy name, and policy type. |
|
<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> actionParamValue="Policy alert when Price is updated for a Laptop"/> |
|
No policy found for this name (Laptop ABCD Policy) and for policyType (update). |
|
|
---|---|
Create Policy for given ServiceItemTypename. /RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName}/policies/create <policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> actionParamValue="Policy alert when Price is updated for a Laptop"/> <status-message code="POLICY_SUCCESS_003"> |
|
<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> actionParamValue="Policy alert when Price is updated for a Laptop"/> <status-message code="POLICY_SUCCESS_003"> <value>Policy updated successfully. </value> |
|
To delete by policy name, the input should be: <policy policyType="quota" name="Laptop Quota policy Fourth"> To delete by policy ID, the input should be: <status-message code="POLICY_SUCCESS_002"> <value>Policy deleted successfully. </value> |
|
|
---|---|
Get requisitions for the current user Get requisitions with the default filter, that is: http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions |
|
RBAC checking is applied against logged-in user. http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitionId> |
|
Retrieves service form data of all the requisition entries of the of the specified requisition ID. The response is a list containing the service name, form field data, and requisitionEntryId for each requisition. The response can be obtained in XML and JSON format. http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitioin_id>/requisitiondata |
|
Submit an existing unsubmitted requisition/cart without adding service(s) to it /RequestCenter/nsapi/transaction/requisitions Request Payload/Body is not needed Response Error Code: Refer to REST/Web Services Error Messages table |
|
Submit a new requisition/cart by adding service(s) to it /RequestCenter/nsapi/transaction/requisitions {"city":"Bangalore", "country": "India"}, {"city":"Mysore", "country":"India"} Response Error Code: Refer to REST/Web Services Error Messages table |
|
Add order to an existing unsubmitted requisition/cart /RequestCenter/nsapi/transaction/requisitions {"city":"Bangalore", "country": "India"}, {"city":"Mysore", "country":"India"} Response Error Code: Refer to REST/Web Services Error Messages table |
|
Cancel an unsubmitted requisition/cart /RequestCenter/nsapi/transaction/requisitions Response Error Code: Refer to REST/Web Services Error Messages table |
|
Remove/Cancel a specific service from a requisition/cart /RequestCenter/nsapi/transaction/requisitionentries/{reqentry_id} Response Error Code: Refer to REST/Web Services Error Messages table |
|
Cancel the monitor plan of an open order The cancelMonitorPlan option of cancel requisition nsAPI cancels the monitor plan of an open order. The status of the requisition is set to Delivery Canceled. /RequestCenter/nsapi/transaction/requisition/{requisitionID}?cancelMonitorPlan=true Response Error Code: Refer to REST/Web Services Error Messages table Note Only a user with Site Administration role has the permission to execute the cancelMonitorPlan option. |
|
Update the Service Request form Updates the form data based on the inputs specified in nsXML http://<ServerURL>/RequestCenter/nsapi/transaction/updateServiceRequest <?xml version="1.0" encoding="UTF-8"?> <message channel-id="" is-autocomplete="false" is-published="true"> <task-started task-type="task"> <data-value multi-valued="false"> <name>GridUpdate-1.Name</name> <value>ordernamechanged4</value> <data-value multi-valued="false"> <name>GridUpdate-1.Roll</name> <value>orderrollchanged4</value> |
|
The views and statuses available for filtering correspond to those in the My Services Requisitions tabs. If Status is not specified, “Ongoing” is used. If ViewName is not specified, “Ordered for Self” is used.
Possible values for Status: Ongoing, Preparation, Ordered, Closed, Canceled, Rejected, All. If an incorrect value is given, the default values (“Ongoing” and “Ordered for Self”) are used. http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/ViewName=<viewName>[|AND|Status=<status>] |
|
Customer Name, Owner (Initiator) Name, Requisition ID, Service Name, Started Date, Status, Submit Date |
|
|
|
Note dueDate and dueDateRaw attributes are available only when asynchronous submission setting is turned off in Administration > Settings module. |
|
http://<ServerURL>/RequestCenter/nsapi/transaction/v1/orderform?serviceids=<list of service ids, comma seperated> |
|
Sample output when the form contains a grid dictionary: Note If a field is multi valued the value of the field is seen as a list and is Multivalued flag is seen for the field. Note If a field is mandatory then the is Mandatory flag is seen for the field. |
|
Sample Input when the Form contains grid dictionaries: Note The payload for the submit requisition APIs can be obtained from the service form details API. Note If the grid dictionary is person based then the login ID must be sent in the place of first name. Note Only form rules with server side events (PostSubmit) are executed. |
1. The Service item definition must be existing to use all of these APIs.
2. The "serviceItemLogicName" in the URL must be a valid one.
3. For Create/Update/Delete inputs, below are the validations:
a. Service Item Name is mandatory.
b. For Create, the same service item should not be present earlier, unlike the Update and Delete.
c. Attributes from the input JSON must exist in the SI definition.
d. The reference records must be existing in order to refer them as reference in parent record - for both Create and Update APIs.
e. The contained records need not be existing in the Update scenario of parent record.
f. On update of a parent record, the contained child record data can be updated, except the 'Name'. The owner information should match for this.
g. Using update of a parent record, user should be able to add an existing SI record as a contained record to another existing SI (parent), if the child record never had any owner SI before.
For Example: Desktop (Parent SI) and CPU (Child SI), and an instance created for both of them separately (Desktop1 and CPU1). Now you can update the Desktop1 and attach the CPU1 to it, if CPU1 never had an owner SI earlier. With this call, CPU1 will become a contained record for Desktop1.
h. On Update, all SI records (parent or contained child records) in the input should be merged and saved. The existing attribute data should not be modified if those attributes are not specified in the input for Update API.
i. The reference records will never be updated with parent record update. They will just be referenced.
j. If you have one contained object for a parent record, and you do not want to have that contained record for the parent, you should pass empty object {} as input if it is single-value contained, or you should pass empty array [] as input if it is multi-value contained.
For example: Harddisk - Single-value contained type attribute. And MultiHardDisk - Multi-value contained type attribute.
k. To update the parent to remove existing reference records, the input structure should be same as above mentioned.
l. "Name" is mandatory for contained/reference child records.
m. If an attribute is not mentioned in the input for Update API, that attribute data will not be modified by update execution.
4. With Delete API, the parent record and also all the child records related to it will be deleted, except the reference records, which are independent of parent record.
5. You can optionally bypass the RBAC check for service item based nsAPIs by setting the serviceitem.nsapi.rbac.check property in the newscale.properties file to false.
Following table describes the nsAPI URLs for doing create/update/delete operations on service item. Request Content-Type can be either of application/xml or application/json. Default response content-type will be the same as Request content-type i.e if the input data is in xml format, response data will also be in xml format. These can be modified by providing additional query parameter 'responseType', whose possible values are 'xml' or 'json'. For example, for an xml input, the response can be got in json format if responseType=json is provided in the URL.
nsAPI is only supported for assigning/revoking permissions for Service Items and Standards. Record level Permissions on SI Instance Data can only be defined from SIM module or through nsAPI (and NOT from Org Designer).
|
|
---|---|
Grants permissions on Service Items and Standards. http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/grantpermission All permissions related to SIM RBAC can be exercised via this nsAPI:
|
|
Revokes permissions on Service Items and Standards. http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/revokepermission All permissions related to SIM RBAC can be exercised via this nsAPI:
|
|
Headers : <Username> <password> and <Content-Type=application/xml> Method=POST Headers : <Username> <password> and <Content-Type=application/xml> Method=POST For more information about the permissions that you can grant/revoke to specific objects, see Permissions that you can grant/revoke to specific objects table. |
Custom content comprises user-defined tables that serve as a source of content for the service portal. Such tables can be referenced as the data source for portlets just like Standards.
The complete list of column names and descriptions for the entities can be found in the “Reference Data” section in the “Designing Portals”, chapter of the Cisco Prime Service Catalog Designer Guide.
|
|
---|---|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/service/{name} |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/category/{name} |
|
REST URL: Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/group/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/person/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/queue/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
http://<ServerURL>/RequestCenter/rexapi/entity/functionalposition/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/role/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/emailtemplate/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/agent/{name} Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/getdata Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/putdata Request Header Parameters: username & password For more information on rex xml, see Example of the Rex XML Structure. |
The Prime Service Catalog administrator globally configures the number of requests allowed and the time-slot (in seconds) for the requests to be allowed through the rate limiter.
The requests (from an external application or within the Prime Service Catalog UI) are accepted as per the configuration and are rejected if they exceed the configuration limit.
When the requests are rejected, the HTTP response code for rate limiting - 429 Too Many Requests (RFC 6585), is returned to the requesting user.
The following global default values are set by the administrator for the rate limiting feature:
In addition, administrator can override the global (default) values using the following qualifiers (Specific URLs, one or more methods will be overridden):
Note You cannot override the time slot. Each override uses the global setting.
Configure rate limit as per the following JSON structure:
Note JSON validation is a manual process. When you save the configuration file nsAPIRateLimit.json,the application does not validate JSON, and would not work in case of an invalid JSON.
Different HTTP response codes are returned by nsAPI depending on the nature of the exceptions:
nsAPI returns an error message if no result is found for the filters provided or if invalid filter criteria is provided. For example:
nsAPI throws an NSAPIException from Java for all exceptions encountered when executing methods in nsAPI.
The chart below provides a summary of operations supported for the different entity types