Skip Navigation LinksALVAO 10.2ALVAO 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

General methods:

AddPersonToGroup
AssignTicketToSolver
BeginUpload
CancelUpload
CreateAct
CreatePerson
CreateTicket
CreateTicketRelation
EndUpload
FindPerson
GetHdSectionsList
GetLastSectionChange
GetPersonCommunicationTickets
GetServiceDeskPortalUrl
GetTicketByMessageTag
GetTicketStateAfterAssignToSolver
GetWebServiceVersion
HasPersonSlaInSection
IsActivated
IsConnectedToDb
IsExistingTicket
IsPersonMemberOfGroup
LogAuditRecord
ReadColumn
RemovePersonFromGroup
ResolveTicket
SendNews
SetTicketState
UploadDataPart
WriteColumn

Methods for sending notifications to requests:

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

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

SendCheckSettingsAlert
SendNonSummaryAlert
SendSummaryAlert

Detailed Description of Methods

General methods

bool AddPersonToGroup(...)

Adds a user to a group.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the "Administrators" system group.

Parameter Data Type Description Required
personId int User identification number (tPerson.iPersonId) Yes
roleId int Group identification number (tRole.iRoleId) Yes

bool AssignTicketToSolver(...)

Assigns the request to a solver.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the solver team of the request's service.

Parameter Data Type Description Required
ticketId int Request identification number Yes
newPersonId 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
personId int Identification number of the person assigning the request to a solver. If the operation is run from an external application, the parameter will be ignored and the request will be assigned by the user who has logged in the web service using integrated authentication. Yes
message string A message for the request solver in plain text No
htmlMessage string A message for the request solver in HTML format No
sendNotification bool Send a request assignment notification 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.

GUID BeginUpload(...)

Start uploading a file to the server.

Parameter Data Type Description Required
filename string File path No
fileType string File type No

void CancelUpload(...)

Canceling the file upload and deleting the temporary file.

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

int CreateAct(...)

Creates a new record in the request log.

Parameter Data Type Description Required
ticketId int ID of the request for which the record is to be created. Yes
creatorId int ID of the person creating the record Yes
subject string Record subject No
message string Message No
htmlMessage string Message with HTML formatting No
senderName string Sender name No
fromEmail string Sender e-mail – for e-mails only No
toEmails string Message recipients – for e-mails only No
ccEmails string E-mail recipients in the Copy field – for e-mails only No
created datetime Record creation date in UTC – for e-mails only Yes
actKindId int Event type for the record in the log, see tActKind. The process (9) and alert (11) event types cannot be used. Yes
showApplicant bool Display the event to the requester Yes

int CreatePerson(...)

Creates a new user. The return value is the identification number (tPerson.iPersonId) of the new user.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the "Administrators" system group.

Parameter Data Type Description Required
fullName string Name and Surname Yes
login string Username No
email string E-mail No
phone string Work phone No
personalNumber string Personal number No

int CreateTicket(...)

Creates a new request. The return value is the number (ID) of the new request.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the solver team of at least one service.

Parameter Data Type Description Required
creatorId int ID of the person recording the request. If the operation is run from an external application, the parameter will be ignored and the request will be recorded by the user who has logged in the web service using integrated authentication. Yes
requesterId int The requester's personal ID Yes
requesterName string First name and surname of the requester No
requesterEmail string The requester's e-mail No
serviceName string Full name of the service where the request will be located. Yes
slaName string SLA name No
subject string Request name No
message string Request Description No
htmlMessage string Request description with HTML formatting No
fromEmail string Sender e-mail – for e-mails only No
toEmails string Message recipients – for e-mails only No
ccEmails string E-mail recipients in the Copy field – for e-mails only No
messageCreated datetime Event creation date in UTC – for e-mails only Yes
ticketCreated datetime Any date – the parameter is not used. Requests are always created in the application server real time.No
actKindId int Event type for the source record, see tActKind. The process (9) and alert (11) event types cannot be used. Yes

int CreateTicketRelation(...)

Creates a link between requests. The return value is the number (ID) of the link between requests.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a user who is a member of the solver team of the service of at least one of the beginTicketId and endTicketId requests and who is authorized to read both requests.

Parameter Data Type Description Required
beginTicketId int Identification number of the source request (from the link's point of view) Yes
endTicketId int Identification number of the end request (from the link's point of view) Yes
ticketRelationTypeId int Link type:
1 – Related to
2 – Is the child of
3 – Follows after
4 – Is blocked by
5 – Duplicates
Or the ID of a custom link type.
Yes
personId int Identification number of the person adding the link. If the value is 0, the action will be executed by _system. If the operation is run from an external application, the parameter will be ignored and the link will be created by the user who has logged in the web service using integrated authentication. No

void EndUpload(...)

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

Parameter Data Type Description Required
sessionId GUID Session identifier returned by the BeginUpload function. Yes
partsCount int Total number of file parts Yes
actId int Record ID in the ServiceDesk log to which the file should be attached Yes
contentId string ID of an attachment inserted in the message body 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
name string First and last name of a person Yes (in no e-mail is filled in)
email string The person's e-mail address Yes (in no name is filled in)

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]

Parameter Data Type Description Required
personId int The person's identification number Yes

DateTime GetLastSectionChange()

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

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
personId int Identification number of the user whose communication you want to display. Yes
ticketsCount int Number of requests (in which the user last communicated) you want to display. Yes

string GetServiceDeskPortalUrl()

Returns the URL of the Service Desk web application.

bool GetTicketByMessageTag(...)

Query for existence of a request with entered symbol.

Parameter Data Type Description Required
text string Request tag No

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
ticketId int 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.

string GetWebServiceVersion()

Returns the current version of the web service.

bool HasPersonSlaInSection(...)

Checks whether the user has any SLAs in the service.

Parameter Data Type Description Required
personId int The person's identification number Yes
sectionId int Service identification number Yes

bool IsActivated(...)

Returns information whether the entered module is activated.

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

bool IsConnectedToDb(...)

Returns the information whether the web service is connected to a specified database.

Parameter Data Type Description Required
serverName string Server name Yes
dbName string Database name Yes

bool IsExistingTicket(...)

Query for request existence.

Parameter Data Type Description Required
ticketId int Request identification number Yes

The method returns true if the ticketId request exists and the calling user has the right to read it. Otherwise, the method returns false.
When calling within custom program extensions, the permissions of the calling user are not checked.

bool IsPersonMemberOfGroup(...)

Returns the information whether the user is a member of a specified database. If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the "Administrators" system group.

Parameter Data Type Description Required
personId int User identification number (tPerson.iPersonId) Yes
roleId int Group identification number (tRole.iRoleId) Yes

void LogAuditRecord(...)

Logs the audit report.

Parameter Data Type Description Required
MessageType int Logged event type. Permitted values:
1 – User creation
2 – User removal
3 – User properties modification
4 – User log-in
5 – User log-out
6 – Unsuccessful user log-in attempt
7 – Permission addition to the service
8 – Service permission change
9 – Service permission removal
10 – SLA addition to the service
11 – Service SLA change
12 – Service SLA removal
13 – Creation of a new permission at the object
14 – Modification of the existing permission at the object
15 – Removal of the existing permission at the object
Yes
Properties NameValuePair[] List of pairs name – value. These items are logged together with the report. Yes

WS at the end of the Properties list will always complete the pair:
WS client address: <IP address>.

string ReadColumn(...)

Returns a value from a table column.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the request data can only be viewed by users who are authorized to view the request; the service data can only be viewed by users who have a role in the service; and the user data can only be viewed by members of the "Administrators" system group.

Parameter Data Type Description Required
recordId int The identification number of a record in the tHdTicket, tHdSection, or tPerson tables. Yes
table string Name of the table to read data from. The following values are supported: tHdTicket, tHdTicketCust, TicketForeignKeyInfo, tHdSection, tPerson, tPersonCust and PersonForeignKeyInfo. Yes
column string Name of a column in a table.
It is possible to read values from all columns of the tHdTicket, tHdTicketCust, and tPersonCust tables.
It is possible to read values from all columns of the tHdSection table except for the columns related to the settings of the mailboxes from which messages are loaded.
It is possible to read values from all columns of the tPerson table except for the user's password and identification data in AD.

When reading data from TicketForeignKeyInfo, the values in the following columns are available for reading:

  • SolverName – the solver's name
  • SolverEmail – the solver's e-mail
  • TicketPriority – the request's priority
  • SectionName – the name of the service where the request is located
  • RoomName – room
  • SLAname – SLA name
  • FirstActText – the original text of the request
When reading data from PersonForeignKeyInfo, the values in the following columns are available for reading:
  • AccountName – name of the user's organization
  • ManagerName – name and surname of the user's manager
  • DelegateName – name and surname of the user's substitute
More information about the columns (including data types) can be found in the ALVAO database documents.

Yes

bool RemovePersonFromGroup(...)

Removes the user from a specified group.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the "Administrators" system group.

Parameter Data Type Description Required
personId int User identification number (tPerson.iPersonId) Yes
roleId int Group identification number (tRole.iRoleId) Yes

void ResolveTicket(...)

Resolves a request. If the request cannot be resolved, the operation will result in an exception.
If the operation is run within custom program extensions, it will be executed under the "_system" account without authorization checks.
If the operation is run from an external application, it will be executed under the user who has logged in the web service using integrated authentication. The method can only be run by a user who has operator or manager authorizations for the request's service or who is the current request solver.

;
ParameterData Type Description Required
ticketId int Request identification number Yes
message string A message for the requester No

void SendNews(...)

Sends the current news to specified recipients.

Parameter Data Type Description Required
newsId int Identification number of the message to be sent. Yes
sendToRequesters bool Send message to requesters of assigned services Yes
sendToSectionTeam bool Send message to members of solver teams of assigned services Yes
specificRecipients string Specific message recipients. Enter an empty string or null if the message has no specific recipients. Yes

void SetTicketState(...)

Changes the request status.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, the method can only be run by a member of the solver team of the request's service.

Parameter Data Type Description Required
ticketId int Request identification number Yes
personId int Identification number of the person changing the request status. If the value is 0, the action will be executed by _system. If the operation is run from an external application, the parameter will be ignored and the request's status will be changed under the user who has logged in the web service using integrated authentication. No
newStateId 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.

void UploadDataPart(...)

Uploading a file part to the server.

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

void WriteColumn(...)

Writes a value to a table column.
If the operation is run within custom program extensions, no authorization checks will be performed.
If the operation is run from an external application, it will be executed under the user who has logged in the web service using integrated authentication. Only users who are members of the solver team of the request's service can run the method for requests. Only users who are members of the "Administrators" system group can run the method for users.

Parameter Data Type Description Required
recordId int Record identification number (tHdTicket or tPerson) Yes
table string The name of a table for writing. The following values are supported: tHdTicket, tHdTicketCust, tPerson and tPersonCust. Yes
column string Name of a column in a table.
It is possible to write to all columns of the tHdTicketCust and tPersonCust tables.

In the tHdTicket table, values can be written to the following columns:

  • mHdTicketNotice
  • sHdTicketCategory
  • sHdTicketGroup
  • sHdTicketDeviceCode
  • sHdTicketUserPhone
  • mHdTicketUserContact
  • sHdTicketUserMobile
  • sHdTicketUserOffice
  • sHdTicketUserDepartment
  • sHdTicketUserWorkPosition
  • sHdTicketUserCompany

In the tPerson table, values can be written to the following columns:

  • sPerson
  • sPersonLogin
  • sPersonAdGuid
  • sPersonEmail
  • sPersonPhone
  • sPersonMobile
  • sPersonOffice
  • sPersonDepartment
  • sPersonWorkPosition
  • bHidden
  • sPersonPswd
  • bPersonShared
  • bPersonAccountDisabled
  • mPersonContact
  • sPersonCalendarWebDAVUri
  • sPersonUrgentEmail
  • dPersonRemoved
  • sPersonCountry
  • sPersonCountryAbbr
  • iPersonCountryCode
  • sPersonCity
  • sPersonAdPath
  • dPersonAdCreated
  • sPersonSID
  • liPersonManagerPersonId
  • sPersonPersonalNumber
  • liPersonDelegatePersonId
  • OutOfOfficeSince
  • iPersonLocaleId
  • sPersonAdName
  • liAccountId
  • sFirstName
  • sLastName
  • sAdDisplayName
  • TimeZone
  • Email2
  • Phone2
  • OutOfOfficeUntil
  • ImportAdLastFound

More information about the columns (including data types) can be found in the ALVAO database documents.

Yes
value string Value inserted in a columnYes

Notifications

void NotifyOnHdTicketAccepted(...)

Sends a notification informing that the request has been approved.

Parameter Data Type Description Required
ticketApprovalItemId int ID of the approval step that has been approved (tHdTicketApprovalItem.iHdTicketApprovalItemId). Yes

void NotifyOnHdTicketApprovalCanceled(...)

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

Parameter Data Type Description Required
ticketId int Request number Yes

void NotifyOnHdTicketApprovalItem(...)

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

Parameter Data Type Description Required
ticketApprovalItemId int ID of the approval step (tHdTicketApprovalItem.iHdTicketApprovalItemId) Yes
personId int Person identifier (tPerson) Yes

void NotifyOnHdTicketApprovalItemFinished(...)

Sends a notification informing approvers that a particular approval step has been completed.

Parameter Data Type Description Required
ticketApprovalItemId int ID of the approval step (tHdTicketApprovalItem.iHdTicketApprovalItemId) Yes

void NotifyOnHdTicketCreated(...)

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

Parameter Data Type Description Required
actId int First request event Yes
notifyUser bool Send a notification to the requester Yes

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
actId int ID of the due date change event Yes
oldDeadline 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
newDeadline datetime New due date of the request; if the date value is less than 1/1/0001, the due date will be canceled. Yes
message string Message – reason for due date change No
htmlMessage string HTML message – reason for due date change No

void NotifyOnHdTicketExpired(...)

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

Parameter Data Type Description Required
ticketId int Request number Yes

void NotifyOnHdTicketHdSectionChanged(...)

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

Parameter Data Type Description Required
actId int ID of the move-to-another-service event Yes
oldHdSectionId int Identifier of the original service; the service has to exist. Yes
newHdSectionId int Identifier of the new service; the service has to exist. Yes
message string Message to solvers/operators No
htmlMessage string HTML message to solvers/operators No

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
actId int ID of the assigned-to-solver event Yes
oldSolverPersonId int Identifier of the original solver; if the value is 0, the request did not have a solver assigned. Yes
newSolverPersonId 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
htmlMessage string HTML message to solvers/operators No

void NotifyOnHdTicketRejected(...)

Sends a notification informing that the request has been rejected.

Parameter Data Type Description Required
ticketApprovalItemId int ID of the approval step that has been rejected (tHdTicketApprovalItem.iHdTicketApprovalItemId). Yes

void NotifyOnHdTicketResolved(...)

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

Parameter Data Type Description Required
actId int Number of event that has resolved a request. Yes
message string Message for requester No
htmlMessage string A HTML message for the requester No

void NotifyOnHdTicketSolverOpen(...)

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

Parameter Data Type Description Required
actId int ID of the request opening event Yes
message string Message – reason for opening the request No
htmlMessage string HTML message – reason for opening the request No

void NotifyOnHdTicketUserOpen(...)

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

Parameter Data Type Description Required
actId int ID of the request opening event Yes
message string Message – reason for opening the request No
htmlMessage string HTML message – reason for opening the request No
sendToSubscribers bool Send a message to the subscribers of the request 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
actId int Identification number of the message event Yes
sendNewMessageNotification 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 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
actId int ID of the due date change event Yes
newDeadline datetime New due date for a request; if the date value is less than 1/1/0001, the due date will be canceled. Yes
message string Message – reason for due date change No
htmlMessage string HTML message – reason for due date change No

void NotifySubscribersOnHdTicketOpen(...)

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

Parameter Data Type Description Required
actId int ID of the request opening event Yes
message string Message – reason for opening the request No
htmlMessage string HTML message – reason for opening the request No

void NotifySubscribersOnHdTicketResolved(...)

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

Parameter Data Type Description Required
actId int Number of event that has resolved a request. Yes
message string Message for requester No
htmlMessage string A HTML message for the requester No

void NotifySubscribersOnMessageSent(...)

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

Parameter Data Type Description Required
actId int ID of the message event Yes

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
hdSectionId int Service identifier Yes
fromName string Name and surname of the message sender No
fromEmail string Message sender e-mail address No
mailTo string Recipient e-mail address (original message sender) No
mailSent string Date of the original message No
mailMessageId string Message identifier No
mailSubject string Subject of the original message No
mailBody 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
ticketId int Request identification number Yes
hdSectionId int Service identifier Yes
fromName string Name and surname of the message sender No
fromEmail string Message sender e-mail address Yes
mailTo string Recipient e-mail address (original message sender) No
mailCc string CC (CarbonCopy) of the original message No
mailSent string Date of the original message No
mailMessageId string Message identifier No
mailSubject string Subject of the original message No
mailBody string Body of the original message No
ticketMark string Tag for the request created when the requester tried to reopen the request after due date. No

Automatic alerts

void SendCheckSettingsAlert(...)

Sends an e-mail notification to system administrators informing them about discovering problems in system setting.

void SendNonSummaryAlert(...)

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

Parameter Data Type Description Required
nAlertId 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
nAlertId int Number of the rule for sending notifications, set in SLA. Yes

 

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