Skip Navigation LinksALVAO 10.0ALVAO Service DeskSystem Implementation in an OrganizationCustom Edits and ExtensionsService Desk WebService - Interface Description Skip Navigation Links. Skip Navigation Links Skip Navigation Links.


Service Desk WebService – Interface Description

This chapter describes the web-based Service Desk interface and methods.

List of Methods

Methods for working with requests:

IsExistingTicket
GetTicketByMessageTag
FindPerson
ResolveTicket
ReadColumn
WriteColumn
CreateTicket
CreateAct
BeginUpload
UploadDataPart
EndUpload
CancelUpload
GetLastSectionChange
GetHdSectionsList
AssignTicketToSolver
GetPersonCommunicationTickets
GetTicketStateAfterAssignToSolver
SetTicketState

Methods for sending notifications to requests:

NotifyOnHdTicketAccepted
NotifyOnHdTicketCreated
NotifyOnHdTicketRejected
NotifyOnHdTicketExpired
NotifyOnHdTicketApprovalCanceled
NotifyOnHdTicketApprovalItem
NotifyOnHdTicketResolved
NotifySubscribersOnHdTicketResolved
NotifyOnMessageSent
NotifySubscribersOnMessageSent
NotifyOnHdTicketPassed
NotifyOnHdTicketHdSectionChanged
NotifyOnHdTicketDeadlineChanged
NotifySubscribersOnHdTicketDeadlineChanged
NotifyOnHdTicketUserOpen
NotifyOnHdTicketSolverOpen
NotifySubscribersOnHdTicketOpen
NotifyUserOnMessageRejected
NotifyUserOnOpenRejected

Methods for sending automatic alerts for requests not being resolved / request due dates:

SendNonSummaryAlert
SendSummaryAlert

Miscellaneous other methods:

IsActivated
GetWebServiceVersion
GetServiceDeskPortalUrl

Detailed Description of Methods

Working with requests

bool IsExistingTicket(...)

Query for request existence.

Parameter Data Type Description Required
Request ID int The request identification number. Yes

bool GetTicketByMessageTag(...)

Query for existence of a request with entered symbol.

Parameter Data Type Description Required
request tag string Request tag. No

int FindPerson(...)

Returns the ID of the first person found (or 0 if no person has been found) based on the specified parameters. At least one parameter has to be specified. Deleted users and users with the Hide in menus property are excluded from the search.

Parameter Data Type Description Required
nname string First and last name of a person. Yes (in no e-mail is filled in)
email string Person's email address. Yes (in no name is filled in)

void ResolveTicket(...)

Resolves a request. The operation will be performed under the "_system" account. If the request cannot be resolved, the operation will result in an exception.

Parameter Data Type Description Required
Request ID int The request identification number. Yes
message string A message to the requester./td>NNo

string ReadColumn(...)

Returns a value from a table column.

Parameter Data Type Description Required
Request ID int The request identification number. Yes
table name string Name of the table to read data from. Supported values: tHdTicket, tHdTicketCust, TicketForeignKeyInfo. Yes
column name string Name of a column in a table. In the case of TicketForeignKeyInfo, the following columns are supported:
- SolverName = name of the request solver
- SolverEmail = email address of the request solver
- TicketPriority = request priority
- SectionName = name of service where the request is located
- RoomName = room
- SLAname = SLA name
- FirstActText = initial request text
Yes

void WriteColumn(...)

Writes a value to a table column.

Note:
You can write into all the columns in the tHdTicketCust table and to the following columns of the tHdTicket table:
mHdTicketNotice, sHdTicketCategory, sHdTicketGroup, sHdTicketHdBranch, sHdTicketDeviceCode, sHdTicketUserPhon, mHdTicketUserContact, sHdTicketUserMobile, sHdTicketUserOffice, sHdTicketUserDepartment, sHdTicketUserWorkPosition, and sHdTicketUserCompany
Parameter Data Type Description Required
Request ID int The request identification number. Yes
table name string Name of the table to read data from. Supported values: tHdTicket, tHdTicketCust. Yes
column name string Name of a column in a table. Yes
value string Value inserted in a column.Yes

int CreateTicket(...)

Creates a new request. The return value is the number (ID) of the new request.

Parameter Data Type Description Required
Person ID int ID of the person creating a request. Yes
Person ID int Requester's personal ID. Yes
name string First and last name of the requester. No
email string Requester email. No
service string Full name of the service where the request will be located. No
SLA string SLA name. No
request name string Request name. No
description string Request description. No
HTML description string Request description with HTML formatting. No
from string Sender email – for emails only. No
to string Message recipients – for emails only. No
copy string Email recipients in the Copy field – for emails only. No
creating event creation date datetime Event creation date in UTC – for e-mails only. Yes
request creation date datetime Request creation date in UTC. If not specified, the creating event creation date will be used. No
Record kind ID string Event type for the source record. Yes

int CreateAct(...)

Creates a new record in the request log.

Parameter Data Type Description Required
Request ID int Request ID for which the record will be created. Yes
Person ID int ID of the person creating the record. Yes
subject string Record subject. No
message string Message. No
HTML message string Message with HTML formatting. No
sender name string Sender name. No
sender email string Sender email – for emails only. No
to string Message recipients – for emails only. No
copy string Email recipients in the Copy field – for emails only. No
date created datetime Creation date of the record in UTC – for emails only. Yes
Record kind ID int Event type for the record in the log. Yes
show to requester bool Display the event to the requester. Yes

GUID BeginUpload(...)

Start uploading a file to the server.

Parameter Data Type Description Required
file string File path. No
type string File type. No

void UploadDataPart(...)

Uploading a file part to the server.

Parameter Data Type Description Required
ID session GUID Session identifier returned by the BeginUpload function. Yes
sequence number int Sequence number of a file part. Yes
data byte[] Binary file data. Yes
size int Size in Bytes of the file being uploaded. Yes

void EndUpload(...)

Finishing file upload to the server and saving the file to the database to the respective record.

Parameter Data Type Description Required
ID session GUID Session identifier returned by the BeginUpload function. Yes
number of parts int Total number of file parts. Yes
Record ID int Record ID in the ServiceDesk log to which the file should be attached. Yes
Attachment ID string ID of an attachment attached to the email body. Optional. No

void CancelUpload(...)

Canceling the file upload and deleting the temporary file.

Parameter Data Type Description Required
ID session GUID Session identifier returned by the BeginUpload function. Yes

DateTime GetLastSectionChange()

Gets the date and time of the last service editing operation.

string[] GetHdSectionsList()

Returns a list of active (not deleted) services (and folders). The data are coded in the list by groups of five:
1. Service ID
2. Service name
3. Location in the service tree
4. Service description – coded as Uri.EscapeDataString
5. This is a folder [0|1]

bool AssignTicketToSolver(...)

Assigns the request to a solver.

Parameter Data Type Description Required
Request ID int The request identification number. Yes
ID of the new solver int Identification number of the person who will become the new request solver. It is not possible to enter an empty value, which means that the request cannot be returned to operator. Yes
ID of the person handing over int Identification number of the person who will assign the request to a solver. No
Message for solver string A message for the request solver in plain text. No
Message for solver (HTML) string A message for the request solver in HTML format. No
Send a notification to the solver bool Send a notification of request assignment to the solver? Yes
When the method is called, the following steps are executed:
  1. Change of request solver
    • Entry in request log
    • Notification of solver change
    • Custom action as necessary
  2. If there is a status on the process with "Switch to this status automatically following the first assignment to solver" enabled and the request originally met the condition for automatic transition to this status (see the GetTicketStateAfterAssignToSolver method), the request status will change (see SetTicketState).
Note:
If the request status cannot be changed (e.g. if required items are not filled in), the request status will not change, but the solver will change.
Note:
The method does not check whether or not the new solver can be the solver for the request.

The method generates events in the log in the language of the service. If sending notifications to solver is not set, the messages for the solver will only be recorded in the log.

string[] GetPersonCommunicationTickets(...)

Displays the overview of requests which logs the person performed the last changes to (last communication of the person).

Parameter Data Type Description Required
User ID int Identification number of the user whose communication you want to display. Yes
Number of requests int Number of requests (in which the user last communicated) you want to display. Yes

void SetTicketState(...)

Changes the request status.

Parameter Data Type Description Required
Request ID int The request identification number. Yes
Person ID int Identification number of the person changing the request status. If not specified, the action will be executed by _system. No
New request status ID int Identification number of the new request status. Yes

When the method is called, the following steps are executed:

  1. Checking required items for the status.
    • Request status change
    • .
      • Resolving/closing the request as necessary.
    • Entry in request log.
    • Custom action as necessary.
    • Starting the approval process as necessary
    • .
      • Entry in request log.
      • Notification to approver.

The method generates events in the log in the language of the service.

int GetTicketStateAfterAssignToSolver(...)

If the status should change after the request is assigned, it returns the ID of the new status. If not, it returns 0.

Parameter Data Type Description Required
Request ID int The request identification number. Yes

When the method is called, the following steps are executed:

  1. 1. Checking whether this is the first assignment to solver and whether a status with "Switch to this status automatically following the first assignment to solver" enabled exists on the process.
    • If yes, it returns the ID of the new status.
    • If not, it returns 0.

Notifications

void NotifyOnHdTicketAccepted(...)

Sends a notification informing the requester that the request has been approved.

Parameter Data Type Description Required
Request ID int Request number. Yes
message string Message for requester. No

void NotifyOnHdTicketCreated(...)

Sends a notification to operators and solvers (possibly also to requester) that a request has been accepted.

Parameter Data Type Description Required
Event ID int First request event. Yes
send to requester bool Send a notification to the requester. Yes

void NotifyOnHdTicketRejected(...)

Sends a notification informing the requester that the request has been rejected.

Parameter Data Type Description Required
Request ID int Request number. Yes
message string Message for requester. No

void NotifyOnHdTicketExpired(...)

Sends a notification that the approval process for the request has expired.

Parameter Data Type Description Required
Request ID int Request number. Yes

void NotifyOnHdTicketApprovalCanceled(...)

Sends a notification that the approval process for the request has been canceled.

Parameter Data Type Description Required
Request ID int Request number. Yes

void NotifyOnHdTicketApprovalItem(...)

Sends a notification that a person needs to approve a request.

Parameter Data Type Description Required
Approval item ID int Approval item number. Yes
Person ID int Person identifier (tPerson). Yes

void NotifyOnHdTicketResolved(...)

Sends a notification informing the requester that the request has been resolved.

Parameter Data Type Description Required
Closing event ID int Number of event that has resolved a request. Yes
message string Message for requester. No

void NotifySubscribersOnHdTicketResolved(...)

Sends a notification informing the notification subscribers that the request has been resolved.

Parameter Data Type Description Required
Closing event ID int Number of event that has resolved a request. Yes
message string Message for requester. No

void NotifyOnMessageSent(...)

Sends a notification to requesters/notification subscribers that a new message has been received regarding a request.

Parameter Data Type Description Required
Event ID int Message event identification number. Yes
message int The value determines whom the message will be send:
-1 – notification will be send only to requester.
-2 – forces notification send to solvers (operators).
-0 – sends standard notification on a new message.
Yes

void NotifySubscribersOnMessageSent(...)

Sends a notification to notification subscribers that a new message has been received regarding a request.

Parameter Data Type Description Required
Event ID int Message event number. Yes

void NotifyOnHdTicketPassed(...)

Sends a notification that the request has been passed on to (a different) solver. The notification is sent both to the original and to the new solver (possibly to operators).

Parameter Data Type Description Required
Event ID int Assigned-to-solver event number. Yes
ID of the original solver int Identifier of the original solver; if the value is 0, the request did not have a solver assigned. Yes
ID of the new solver int Identifier of the new solver; if the value is 0, the request was returned to the operators. Yes
message string Message to solvers/operators. No

void NotifyOnHdTicketHdSectionChanged(...)

Sends a notification informing the requester that the request has been moved to a different service.

Parameter Data Type Description Required
Event ID int Move-to-different-service event number. Yes
ID of the original service int Identifier of the original service; the service has to exist. Yes
ID of the new service int Identifier of the new service; the service has to exist. Yes
message string Message to solvers/operators. No

void NotifyOnHdTicketDeadlineChanged(...)

Sends a notification to the requester that a due date has been set/changed/canceled for his/her request.

Parameter Data Type Description Required
Event ID int Change due date event number. Yes
original due date datetime Original due date of the request; if the date value is less than 1/1/0001, the original due date was empty, which means that in this case you are working with a new due date. Yes
new due date datetime New due date of the request; if the date value is less than 1/1/0001, the due date will be canceled. Yes
reason string Message – reason for due date change. No

void NotifySubscribersOnHdTicketDeadlineChanged(...)

Sends a notification to the notification subscribers that a due date has been set/changed/canceled for their request.

Parameter Data Type Description Required
Event ID int Change due date event number. Yes
new due date datetime New due date for a request; if the date value is less than 1/1/0001, the due date will be canceled. Yes
reason string Message – reason for due date change. No

void NotifyOnHdTicketUserOpen(...)

Sends a notification to the request solver that the requester has reopened his/her request.

Parameter Data Type Description Required
Event ID int Request-open event number. Yes
reason string Message – reason for opening the request. No

void NotifyOnHdTicketSolverOpen(...)

Sends a notification to the requester that the solver has reopened his/her request.

Parameter Data Type Description Required
Event ID int Request-open event number. Yes
reason string Message – reason for opening the request. No

void NotifySubscribersOnHdTicketOpen(...)

Sends a notification informing the notification subscribers that the request has been reopened.

Parameter Data Type Description Required
Event ID int Request-open event number. Yes
message string Message – reason for opening the request. No

void NotifyUserOnMessageRejected(...)

Sends a notification to the requester that his/her request has been rejected because the requester does not have the permission to use the service.

Parameter Data Type Description Required
Service ID int Service identifier. Yes
sender name string Name and surname of the message sender. No
sender email string Message sender email address. No
recipient email string Recipient email address (original message sender). No
date string Date of the original message. No
Message ID string Message identifier. No
subject string Subject of the original message. No
text string Body of the original message. No

void NotifyUserOnOpenRejected(...)

Sends a notification to the requester that the reopening his/her request has been rejected.

Parameter Data Type Description Required
Request ID int The request identification number. Yes
Service ID int Service identifier. Yes
sender name string Name and surname of the message sender. No
sender email string Message sender email address. Yes
recipient email string Recipient email address (original message sender). No
Recipient CC string CC (CarbonCopy) of the original message. No
date string Date of the original message. No
Message ID string Message identifier. No
subject string Subject of the original message. No
text string Body of the original message. No
Request tag string Tag for the request created when the requester tried to reopen the request after due date. No

Automatic alerts

void SendNonSummaryAlert(...)

Sends all notifications immediately (requests not being resolved, due date) related to entered request.

Parameter Data Type Description Required
Rule ID int Number of the rule for sending notifications, set in SLA. Yes

void SendSummaryAlert(...)

Sends summary notification (requests not being resolved, due date), but only if it is set to be sent at the current hour.

Parameter Data Type Description Required
Rule ID int Number of the rule for sending notifications, set in SLA. Yes

Other methods

bool IsActivated(...)

Returns information whether the entered module is activated.

Parameter Data Type Description Required
Module ID int Identification number of the module you want to authenticate. Yes

string GetWebServiceVersion()

Returns the current version of the web service.

string GetServiceDeskPortalUrl()

Returns the URL of the Service Desk web application.

 

Did not find what you were looking for? Ask our technical support team.