Request Attributes and xml Response
The request attributes for all request operations should be defined as mentioned. The operations on requests are based on the "Roles" assigned to the users.
Note |
1. Attributes are case sensitive and should be used as defined. 2. Operations on request can be performed based on the Roles assigned to the user. 3. While renaming the button in the sample html form, specify 'operation' as hidden element. |
To create a new request, the targetURL attribute should be set to /servlets/RequestServlet and the 'operation' attribute should be 'AddRequest'. The 'account', 'site' and 'requester' parameters are mandatory for creating a request.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for Adding Request |
operation='AddRequest' |
Operation command for Adding Request |
reqTemplate |
name of the Request Template |
title |
Subject of the request |
description |
Description of the request |
resolution |
Resolution |
requester |
Requester |
requesterEmail |
Email Id of Requester |
priority |
Priority |
level |
Level |
status |
Status |
mode |
Mode |
urgency |
Urgency |
impact |
Impact |
impactDetails |
Impact Details |
requesttype |
RequestType |
account |
Account |
site |
Site |
category |
Category |
subcategory |
SubCategory |
item |
Item |
group |
Group |
technician |
Technician Name |
technicianEmail |
Technician EmailID |
asset |
Name of the asset assigned to the request |
assetId |
ID of he asset assigned to the request |
UDF Alias Name |
name of the UDF field specified while creating the field. |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. AD_AUTH refers to Active Directory Authentication. Local Authentication or empty value refers to Local Authentication. |
Note:
-
Requester and Technician are set based on their User Name and Email ID.
-
While creating a request with a Requester Login credentials, the Site field is set with the site of the requester.
-
While creating request through Requester Login credentials, the Requester is restricted to creating requests for the assets associated to him/her only if the option Show workstations associated to requester in Self-Service Portal is selected under Admin -> Self Service Portal Settings.
-
While creating a request, if Subject field is left empty, then '(no subject)' is set as subject for the Request.
-
If a field is not available for a request template but given through API, then the field is discarded.
-
While creating a request, if the mandatory fields specified in Request Template are not provided, then the request is created with the information provided by RequestServlet and a System Log is populated with an error message.
The sample form to create request can be accessed here.
The html form should be submitted to http://machine_name:Port_Number/servlets/RequestServlet and a response in xml format displays "Success" message along with the WorkOrder ID.
If the technician creating the request does not have permission to create new requests or has limited access permissions a "Failure" message appears in the xml form.
To update a request, the targetURL attribute should be set to /servlets/RequestServlet and the 'operation' attribute should be 'UpdateRequest'. The 'account', 'site', 'requester' and 'workOrderID' parameters are mandatory for updating a request.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for updating Request |
operation='UpdateRequest' |
Operation command for Updating Request |
workOrderID |
Request ID of the request to update. |
reqTemplate |
name of the Request Template |
title |
Subject of the request |
description |
Description of the request |
resolution |
Resolution |
requester |
Requester |
requesterEmail |
Email Id of Requester |
priority |
Priority |
level |
Level |
duebytime |
Due By time to be applied for the request |
status |
Status |
mode |
Mode |
urgency |
Urgency |
impact |
Impact |
impactDetails |
Impact Details |
requesttype |
RequestType |
account |
Account |
site |
Site |
category |
Category |
subcategory |
SubCategory |
item |
Item |
group |
Group |
technician |
Technician Name |
technicianEmail |
Technician EmailID |
asset |
Name of the asset assigned to the request |
assetId |
ID of he asset assigned to the request |
UDF Alias Name |
name of the UDF field specified while creating the field. |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. "AD_AUTH" refers to Active Directory Authentication. "Local Authentication" or empty value refers to Local Authentication. |
Note:
-
Requester and Technician are identified based on their User Name and EmailID.
-
Empty Values can be updated to the request by passing the value as NULL .
-
Requester cannot update a request.
A sample form for updating requests can be viewed here.
A Success message appears in a xml format if the request is updated successfully.
If the technician does not have permission to update the request ( Edit Request permission under Roles), a Failure message appears in the xml form.
In some cases, the request may not fall under the technician's scope. For instance, a technician with permission to view 'Requests assigned to him only' cannot update a request that is not assigned to him although he has the 'Update Request' permission.
Click here to view the xml response for a update-failed request.
Assign Request to a Technician
To assign a request to a technician, use the same operation as described above for 'Update Request'. Pass the 'Technician Name', 'Technician Email' and 'WorkorderID' parameters with the request. A requester cannot assign a request to a technician.
The sample form for assigning/picking up request is similar to that of Updating requests. Requests are assigned to technicians associated to the specified site. If Group is mentioned, the technician should belong to the group. If the request is assigned to a technician unassociated to the site, the response in xml format does not display an error message. But the request is not assigned to the technician.
A request can be closed in two ways,
-
Set the 'status' parameter as 'Closed' along with the 'workOrderID' parameter (mandatory parameter) and operation command as 'UpdateRequest'. (See above for 'UpdateRequest')
-
Set 'workOrderID' parameter (mandatory for request update) and 'operation' command as 'CloseRequest'. Set the 'Close comments' parameter as 'closeComment'. The Close Comment can be added, if 'Confirm User Acknowledgment' is selected as 'YES' in 'Request Closing Rules'. A Requester does not have permission to close a request.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for closing Request |
operation='CloseRequest' |
Operation command for closing Request |
workOrderID |
Request ID of the request to close. |
closeComment |
Close Comments |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. AD_AUTH refers to Active Directory Authentication. Local Authentication or empty value refers to Local Authentication. |
The sample form to close request can be accessed here.
A success message appears in xml format on submitting the form to http://machine_name:Port_Number/servlets/RequestServlet.
If the specified request ID does not exist, the message "WorkOrder not found for ID : 20" appears in the xml form.
If the technician has restricted access permission or does not have permission to close the request then a Warning message appears in the xml form.
To delete a request, set the parameter value for 'operation' attribute as 'DeleteRequest' along with 'workOrderID'.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for deleting Request |
operation='DeleteRequest' |
Operation command for Deleting Request |
workOrderID |
Request ID of the request to delete. |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. "AD_AUTH" refers to Active Directory Authentication. "Local Authentication" or empty value refers to Local Authentication. |
The sample form to delete requests can be viewed here.
A Success message appears if the technician has permission to delete the request.
If a technician without delete permission or with restricted viewing permission, is trying to delete a request then a Failure message appears as the xml response.
To add notes to a request, set the parameter value for 'operation' attribute as 'AddNotes' along with 'workOrderID'.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for adding notes to request |
operation='AddNotes' |
Operation command for closing Request |
workOrderID |
Request ID of the request to add notes |
notesText |
Notes to be added to the given Request Id |
isPublic |
isPublic=true denotes Public Notes isPublic=false denotes Private NotesClose Comments |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. AD_AUTH refers to Active Directory Authentication. Local Authentication or empty value refers to Local Authentication. |
The sample form to add notes can be accessed here.
Technicians with permission for the request module can add notes. A Success message appears if the note is added successfully.
Conversely, technicians without permission (Edit permission under Roles) cannot add a note and a 'Failure message' appears if they try to add a note.
To add worklog to a request, set the parameter value for 'operation' attribute as 'AddWorkLog' along with 'workOrderID'.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for adding notes to request |
operation='AddWorkLog' |
Operation command for adding worklog to request |
workOrderID |
Request ID |
technician |
Technician Resolving the Request |
technicianEmail |
Email-ID of technician Resolving the Request |
description |
description |
workHours |
Time Taken To Resolve in hours |
workMinutes |
Time Taken To Resolve in minutes |
cost |
Incident Cost |
executedTime |
Executed Time |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. AD_AUTH refers to Active Directory Authentication. Local Authentication or empty value refers to Local Authentication. |
Note:
-
If the fields, 'technician' and 'technicianEmail' are left blank, the logged in technician is considered as the technician resolving the request.
-
If the 'cost' field remains empty, then 'cost per hour' will be taken as the Incident Cost.
-
If the execution time is left blank, the current time is taken as the 'execution time'.
-
The Execution Time should be in the format 'dd MMM yyyy, HH:mm:ss[01 Jul 2010, 18:02:26]'.
The sample form to add Worklog can be accessed here.
A Success message appears along with the 'requestChargeID' in xml format on submitting the form to http://machine_name:Port_Number/servlets/RequestServlet.
If the technician is not provided with the role to add worklog, a Failure message appears in the xml response.
If the technician does not have access to the request, a Failure message appears in XML format. Click here to view the response.
To delete a worklog, set the parameter value for 'operation' attribute as 'DeleteWorkLog' along with 'requestChargeID'.
Attribute |
Comment |
targetURL="/servlets/RequestServlet" |
Operation target url for deleting worklog |
operation='DeleteWorkLog' |
Operation command for Deleting worklog |
requestChargeID |
WorkLog ID to delete |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. "AD_AUTH" refers to Active Directory Authentication. "Local Authentication" or empty value refers to Local Authentication. |
The Delete WorkLog sample form can be accessed here.
The worklog is deleted successfully if the technician has permission to delete the Worklog. Click here to view the xml response.
To view a request details, set the parameter value for 'operation' attribute as 'GetRequestDetails' along with 'workOrderID'.
Attribute |
Comment |
GetRequestDetails |
Operation command for Getting Request Details |
workOrderID |
Request ID |
username |
Login Name for ServiceDesk Plus - MSP Authentication |
password |
Password for ServiceDesk Plus - MSP Authentication |
DOMAIN_NAME |
Domain Name to which the user belongs. Domain Name needs to be specified on selecting AD authentication. |
logonDomainName |
Authentication Mode [AD or Local Authentication]. AD_AUTH refers to Active Directory Authentication. Local Authentication or empty value refers to Local Authentication. |
The sample form to view the request details can be accessed here.
The request details is displayed as the response in xml if the technician has permission to view requests. The fields unspecified in the form are set as 'null' as shown.
A failure message appears as shown if the technician does not have permission to view requests or has restricted access permission.