Contract Related Operations
While invoking the contract related operations through API, the operation defined are based on the parameter value, and the developer needs to submit a request to the url via HTTP POST or GET method.
NOTE: Before proceeding with the contract related operations and its corresponding parameters, please note that the parameters are case sensitive and should be used as defined.
The following operations can be performed on a contract through API,
Add Contract
Through this operation, you can add contract.
URL Format
The URL format for the Contract operation - Add
For xml output
http://<server-name>:<port-number>/api/xml/addContract
For json output
http://<server-name>:<port-number>/api/json/addContract
|
Parameters
The parameters that needs to be passed via HTTP method for adding a new contract are as follows,
Parameter
|
Value
|
Description
|
account
|
string
|
Denotes the Account name.
|
contractName
|
string
|
The name of the contract.
|
contractNumber
|
string
|
Denotes the contract number.
|
description
|
string
|
Description of the new contract.
|
supportPlan
|
string
|
The name of the support plan which you would like to add it to contract.
|
products
|
string
|
The list of products that has to be associated to the contract.
|
fromDate
|
string
|
The start date of the contract.
|
toDate
|
string
|
The end date of the contract.
|
noOfHrs
|
string
|
The number of hours of contract.
|
noOfMins
|
string
|
The number of minutes of contract.
|
noOfIncidents
|
string
|
The number of incidents of contract.
|
totalCost
|
string
|
Total cost to be paid for the contract.
|
supportPlanRates
|
string
|
The support plan types and the corresponding rates fixed to each support plan.
|
services
|
string
|
The list of support services offered.
|
ifAvailable
|
string
|
If the contract name is already available, you can use this to perform other operations such as update/renew contract.
|
businessUnit
|
string
|
Name of the business unit.
|
NOTE:
-
Please note that the Account, Contract Name, Support Plan and From Date are mandatory fields to be entered while creating a new contract. If multi tenancy is enabled through Business Units and if the application has more than one Business Unit configured, then Business Unit becomes a mandatory field.
-
The From Date and To Date should be specified in "yyyy-MM-dd" format.
-
The "ifAvailable" parameter can be used when importing contracts from CSV, if the contract name already exists you can specify renew/update the contract.
-
To create contract with all products, provide products=AllProducts.
-
Depending upon the type of Support Plan, the noOfHrs, noOfMins and noOfIncidents can be configured.
-
While sending multiple values for products, separate them with comma and with no spaces. (For example, products=Desktop,Laptop,Printer).
-
The "supportPlanRates" parameter should be specified as supportPlanRates=Rate. (For example, supportPlanRates=Normal Rate=100,After-Hours Rate=200).
-
If To Date is not specified while creating contract, then the contract will be created forever without out any end date.
Output Response Format
The output response format for both xml and json consists of three parameters:
-
response uri: The response uri is the url value sent over HTTP POST method.
-
status: The status denotes the status of the operation. Here there are only two status - Success and Failure.
-
statuscode: The statuscode denotes the code displayed when the status is Success or Failure. For a successful operation, the status code is 200.
Success
When the operation is successful, the output response format is as given below,
response uri=[url value]
status=Success
statuscode=200
Sample Response
response uri="api/xml/addContract"
status=Success
statuscode=200
|
Error
Errors occur when the API Key is not valid or the parameter value does not exist in the application. In such cases, the output format is as shown below,
response uri=[url value]
status=Failure
statuscode=failurecode
Sample Response
response uri="api/xml/addContract"
status=Failure
statuscode=4000
statusmessage=No product with the specified name exists.
|
Sample Input Form
Sample form for the operation 'addContract' is given below,
<form method="POST" action="http(s)://<server-name>:<port-number>/api/xml/'addContract'">
<input type="hidden" name="apikey" value="[SupportCenter API Key]">
<input type="text" name="contractName" value="[Name of the contract]">
<input type="text" name="account" value="[Name of the account]">
<input type="text" name="fromDate" value="[From Date]">
<input type="submit" name="submit" value="submit">
</form>
View/Read Contract
URL Format
The URL format for the Contract operation - View/Read
For xml output
http://<server-name>:<port-number>/api/xml/getContract
For json output
http://<server-name>:<port-number>/api/json/getContract
|
Parameters
The parameters that needs to be passed via HTTP method for viewing a contract are as follows,
Parameter
|
Value
|
Description
|
contractName
|
string
|
Name of the Contract.
|
id
|
string
|
Contract ID of the contract to view.
|
businessUnit
|
string
|
Name of the business unit.
|
NOTE:
-
Please note that while performing the 'getContract' operation, either the Contract Name or Contract ID should be specified.
-
If multi tenancy is enabled through Business Units and if the application has more than one Business Unit configured, then Business Unit becomes a mandatory field.
Output Response Format
The output response format for both xml and json consists of three parameters:
-
response uri: The response uri is the url value sent over HTTP POST or GET method.
-
status: The status denotes the status of the operation. Here there are only two status - Success and Failure.
-
statuscode: The statuscode denotes the code displayed when the status is Success or Failure. For a successful operation, the status code is 200.
Success
When the operation is successful, the output response format is as given below,
response uri=[url value]
status=Success
statuscode=200
Sample Response
response uri="api/xml/getContract"
status=Success
statuscode=200
|
Error
Errors occur when the API Key is not valid or the parameter value does not exist in the application. In such cases, the output format is as shown below,
response uri=[url value]
status=Failure
statuscode=failurecode
Sample Response
response uri="api/xml/getContract"
status=Failure
statuscode=5003
statusmessage=Contract id specified does not exist.
|
Sample Input Form
Sample form for the operation 'getContract' is given below,
<form method="GET" action="http(s)://<server-name>:<port-number>/api/xml/getContract">
<input type="hidden" name="apikey" value="[SupportCenter API Key]">
<input type="text" name="id" value="[Contract ID of contract to view]">
<input type="submit" name="submit" value="submit">
</form>
Update Contract
This operation updates the Contract.
URL Format
The URL format for the Contract operation - Update
For xml output
http://<server-name>:<port-number>/api/xml/updateContract
For json output
http://<server-name>:<port-number>/api/json/updateContract
|
Parameters
Either of the following parameters should be passed via HTTP method.
Parameter
|
Value
|
Description
|
account
|
string
|
Denotes the Account name.
|
contractName
|
string
|
The name of the contract.
|
contractNumber
|
string
|
Denotes the contract number.
|
id
|
string
|
Denotes the Contract ID.
|
description
|
string
|
Description of the contract.
|
supportPlan
|
string
|
The name of the support plan.
|
products
|
string
|
The list of products associated to the contract.
|
fromDate
|
string
|
The start date of the contract.
|
toDate
|
string
|
The end date of the contract.
|
noOfHrs
|
string
|
The number of hours of contract.
|
noOfMins
|
string
|
The number of minutes of contract.
|
noOfIncidents
|
string
|
The number of incidents of contract.
|
totalCost
|
string
|
Total cost to be paid for the contract.
|
supportPlanRates
|
string
|
The support plan types and the corresponding rates fixed to each support plan.
|
services
|
string
|
The list of support services offered.
|
businessUnit
|
string
|
Name of the business unit.
|
newContractName
|
string
|
The new contract name that can be set while updating the contract.
|
NOTE:
-
Please note that while performing the 'updateContract' operation, either the Contract Name or Contract ID should be specified. If multi tenancy is enabled through Business Units and if the application has more than one Business Unit configured, then Business Unit becomes a mandatory field.
-
The From Date and To Date should be specified in "yyyy-MM-dd" format.
-
To create contract with all products, provide products=AllProducts.
-
Depending upon the type of Support Plan, the noOfHrs, noOfMins and noOfIncidents can be configured.
-
While sending multiple values for products, separate them with comma and with no spaces. (For example, products=Desktop,Laptop,Printer).
-
The "supportPlanRates" parameter should be specified as supportPlanRates=Rate. (For example, supportPlanRates=NormalRate=100,After-Hours Rate=200).
Output Response Format
The output response format for both xml and json consists of three parameters:
-
response uri: The response uri is the url value sent over HTTP POST or GET method.
-
status: The status denotes the status of the operation. Here there are only two status - Success and Failure.
-
statuscode: The statuscode denotes the code displayed when the status is Success or Failure. For a successful operation, the status code is 200.
Success
When the operation is successful, the output response format is as given below,
response uri=[url value]
status=Success
statuscode=200
Sample Response
response uri="api/xml/updateContract"
status=Success
statuscode=200
|
Error
Errors occur when the API Key is not valid or the parameter value does not exist in the application. In such cases, the output format is as shown below,
response uri=[url value]
status=Failure
statuscode=failurecode
Sample Response
response uri="api/xml/updateContract"
status=Failure
statuscode=5000
statusmessage=Permission denied.
|
Sample Input Form
Sample form for the operation 'updateContract' is given below,
<form method="POST" action="http(s)://<server-name>:<port-number>/api/xml/updateContract">
<input type="hidden" name="apikey" value="[SupportCenter API Key]">
<input type="text" name="id" value="[Contract ID of the contract]">
<input type="submit" name="submit" value="submit">
</form>
Renew Contract
This operation renews the existing contract.
URL Format
The URL format for the Contract operation - Renew
For xml output
http://<server-name>:<port-number>/api/xml/renewContract
For json output
http://<server-name>:<port-number>/api/json/renewContract
|
Parameters
Either of the following parameters should be passed via HTTP method.
Parameter
|
Value
|
Description
|
id
|
string
|
Denotes the Contract ID.
|
contractName
|
string
|
The name of the contract.
|
products
|
string
|
The list of products associated to the contract.
|
fromDate
|
string
|
The start date of the contract.
|
toDate
|
string
|
The end date of the contract.
|
noOfHrs
|
string
|
The number of hours of contract.
|
noOfMins
|
string
|
The number of minutes of contract.
|
noOfIncidents
|
string
|
The number of incidents of contract.
|
totalCost
|
string
|
Total cost to be paid for the contract.
|
supportPlanRates
|
string
|
The support plan types and the corresponding rates fixed to each support plan.
|
services
|
string
|
The list of support services offered.
|
businessUnit
|
string
|
Name of the business unit.
|
NOTE:
-
Please note that while performing the 'renewContract' operation, either the Contract Name or Contract ID should be specified and From Date is mandatory field. If multi tenancy is enabled through Business Units and if the application has more than one Business Unit configured, then Business Unit becomes a mandatory field.
-
The From Date and To Date should be specified in "yyyy-MM-dd" format.
-
To renew contract with all products, provide products=AllProducts.
-
If To Date is not specified while renewing contract, then the contract will be renewed forever without any end date.
Output Response Format
The output response format for both xml and json consists of three parameters:
-
response uri: The response uri is the url value sent over HTTP POST or GET method.
-
status: The status denotes the status of the operation. Here there are only two status - Success and Failure.
-
statuscode: The statuscode denotes the code displayed when the status is Success or Failure. For a successful operation, the status code is 200.
Success
When the operation is successful, the output response format is as given below,
response uri=[url value]
status=Success
statuscode=200
Sample Response
response uri="api/xml/renewContract"
status=Success
statuscode=200
|
Error
Errors occur when the API Key is not valid or the parameter value does not exist in the application. In such cases, the output format is as shown below,
response uri=[url value]
status=Failure
statuscode=failurecode
Sample Response
response uri="api/xml/renewContract"
status=Failure
statuscode=5000
statusmessage=No contract with specified ID exists.
|
Sample Input Form
Sample form for the operation 'renewContract' is given below,
<form method="GET" action="http(s)://<server-name>:<port-number>/api/xml/getRequestFilters">
<input type="hidden" name="apikey" value="[SupportCenter API Key]">
<input type="text" name="businessUnit" value="[Business Unit]">
<input type="text" name="id" value="[Contract ID]">
<input type="text" name="fromDate" value="[From Date]">
<input type="submit" name="submit" value="submit">
</form>