Environment
Service Desk Web Access 7.4 onwards
Introduction
This document provides a JavaScript library to assist web developers that want to integrate with Web Access. Web Access provides APIs to interact with Service Desk from any web page hosted on the same server. However they are not fully documented or intuitive for first time users. The attached library is intended to address that and supply an easy to use set of commands.
Using this library you can write pages that are hosted within Web Access dashboard gadgets or within <iframe> tags of external websites. You can query data, create/update/delete records, and perform various types of process action.
Note: This is intended for web developers with experience of JavaScript and the basic concepts of Service Desk.
Support / Feedback
This library is supplied completely "as is" and is not officially supported by LANDESK. You can log any issues on the Community although there is no guarantee you will receive a response or solution.
Installation / Configuration
First download the .js file attached to this document and copy it to a location on your Service Desk web server. It is recommended to create a folder at the website root to store your .js and .html files. Do not store them under the Web Access folder itself. A sample .html file is also supplied which can be used as a reference for every command.
With the .js file in place reference it from a .html file and you can then run any of the supported commands. All commands take a single object as its parameter. This object must have specific named properties relevant for that command. The reason behind this design is for readability and the flexibility of having multiple optional attributes.
Initiating The Connection
Create an instance of the webAccessConnector object to a variable with the parameter webAccessUrl. This can be either a relative or full Url, however note that a full Url must point to the same server as the page calling it. Without any other parameters this will assume the user is already logged in to Web Access or that you are using integrated logon. You can optionally add parameters loginOnDemand, loginUser, loginPass to automatically log in explicitly with the specified credentials:
var webConn = new webAccessConnector({ webAccessUrl: "/ServiceDesk.WebAccess", loginOnDemand: true, loginUser: "sa", loginPass: "administrator"
});
Running Commands
Once the connection is initiated you can now run asynchronous commands. Every command allows you to supply a function to call on success and failure of that command. In both cases the function will need to receive a single parameter which will have various properties available.
The object supplied to the function specified for successful completion of a command have the following properties:
- data: The returned data from the command. Apart from a couple of types of process actions this will be an object with various relevant properties.
- response: The raw XMLHttpRequest object.
The object supplied to the function used failed commands have the following properties:
- statusCode: The HTTP status code, ie. 401, 500, etc.
- errorText: The reason for the failure.
Here are some example functions:
function handleFail(result) { document.getElementById("testResult").innerHTML = "Error: " + result.errorText;
}
function handleResult(result) {
document.getElementById("testResult").innerHTML = JSON.stringify(result.data);
}
Query Commands
The following commands are available to perform queries:
query.runConsoleQuery
Run a Console designed query and optionally apply a report template and custom page size. Note that without a report template the query will only return basic data (Guid, "name" value, etc) about each record and will not bring back the columns used in the query design.
Parameter properties:
- className: The name of the object the query is designed against in format ModuleName.ObjectName, ie. IncidentManagement.Incident.
- queryName: The system name of the query to run. To obtain the system name run the query in Web Access and look in the Url
- templateName: (optional) The name of the report template to apply.
- pageSize: (optional) A custom number of records to return per page (you can only return the first page with this command).
- onLoad: The function to run on successful completion.
- onError: The function to run on failure.
webConn.query.runConsoleQuery({ className: "IncidentManagement.Incident", queryName: "_IncidentsAwaitingResponse2", onLoad: handleResult, onError: handleFail
});
The data property of the returned object will contain various properties listing the results plus a count of the total number of results.
query.runQuery
Run a query supplying information about the query design. This information should be in the same format as a Web Access query URL but passed in a structured object.
Parameter properties:
- queryData: An object containing the query design:
- class_name: The name of the object to query.
- attributes: A list of attributes to return.
- cns: The criteria of the query.
- c(n): The criteria values starting at c0 and incrementing up c1, c2, etc.
- onLoad / onError: The functions to run on completion/failure.
var myQuery = { class_name: "IncidentManagement.Incident", attributes: "Title,Status", cns: "RaiseUser-ne-0", c0: "d2ba61a5-f0c7-4904-b02a-362a3b348899" };
webConn.query.runQuery({ queryData: myQuery, onLoad: handleResult, onError: handleFail
});
Record Commands
The following commands are available to create and manipulate object records:
record.createRecord
Create an object record.
Parameter properties:
- className: The name of the object to create a record for.
- attributeValues: (optional) An object containing the attributes to set values for and their respective values.
- onLoad / onError: The functions to run on completion/failure.
var myValues = { Title: "my notice" };
webConn.record.createRecord({ className: "System.NoticeboardItem", attributeValues: myValues, onLoad: handleResult, onError: handleFail
});
record.createProcessRecord
Create a process record. This is an alternative to calling record.createRecord for process records.
Parameter properties:
- className: The name of the object to create a record for.
- lifecycleName: The name of the process to create the record with.
- templateName: (optional) The name of a template to apply on the record.
- attributeValues: (optional) An object containing the attributes to set values for and their respective values.
- onLoad / onError: The functions to run on completion/failure.
var myValues = { Title: "Hello world", Description: "This is the description" };
webConn.record.createProcessRecord({ className: "IncidentManagement.Incident", lifecycleName: "NewProcess111", templateName: "PasswordReset0", attributeValues: myValues, onLoad: handleResult, onError: handleFail
});
record.openRecord
Open the full details of an existing record.
Parameter properties:
- className: The name of the object to create a record for.
- key: The primary key (Guid) of the record to open.
- onLoad / onError: The functions to run on completion/failure.
webConn.record.openRecord({ className: "System.User", key: "2cba4bd5-c208-4733-a858-a35cf02ee30f", onLoad: handleResult, onError: handleFail
});
record.updateRecord
Update some values on an existing record.
Parameter properties:
- className: The name of the object to create a record for.
- key: The primary key (Guid) of the record to open.
- attributeValues: An object containing the attributes to update values for and their respective values.
- onLoad / onError: The functions to run on completion/failure.
var myValues = { Description: "This is the NEW description", Category: "b6363e4a-042b-4d5b-8ee4-379c1ca44cc2" };
webConn.record.updateRecord({ className: "IncidentManagement.Incident", key: "afc412f9-819b-4feb-81c3-30c7e0b9bf0e", attributeValues: myValues, onLoad: handleResult, onError: handleFail
});
record.deleteRecord
Delete an existing record.
Parameter properties:
- className: The name of the object to delete a record for.
- key: The primary key (Guid) of the record to delete.
- onLoad / onError: The functions to run on completion/failure.
webConn.record.deleteRecord({ className: "System.NoticeboardItem", key: "65398473-ea24-4c25-b017-c7c4133b3c11", onLoad: handleResult, onError: handleFail
});
Process Action Commands
The following commands are available to perform different types of process actions.
action.collectionAction
Perform a standard collection action.
Parameter properties:
- processClassName: The name of the process object to perform the action against.
- processKey: The primary key (Guid) of the process record.
- actionName: The name of the collection action to perform.
- collectionClassName: The name of the object the action will create.
- attributeValues: (optional) An object containing the attributes to set values for and their respective values.
- onLoad / onError: The functions to run on completion/failure.
var myValues = { Text: "note text" };
webConn.action.collectionAction({ processClassName: "IncidentManagement.Incident", processKey: "f0592a1c-eb47-41f5-a58a-493b39d5efca", actionName: "AddNote", collectionClassName: "IncidentManagement.Note", attributeValues: myValues, onLoad: handleResult, onError: handleFail
});
action.updateAction
Perform an update action.
Parameter properties:
- className: The name of the process object to perform the action against.
- key: The primary key (Guid) of the process record.
- actionName: The name of the update action to perform.
- attributeValues: An object containing the attributes to set values for and their respective values.
- onLoad / onError: The functions to run on completion/failure.
var myValues = { Description: "new description" };
webConn.action.updateAction({ className: "IncidentManagement.Incident", key: "f0592a1c-eb47-41f5-a58a-493b39d5efca", actionName: "CompleteMandatoryData", attributeValues: myValues, onLoad: handleResult, onError: handleFail
});
action.windowlessAction
Perform a windowless action.
Parameter properties:
- className: The name of the process object to perform the action against.
- key: The primary key (Guid) of the process record.
- actionName: The name of the windowless action to perform.
- onLoad / onError: The functions to run on completion/failure.
webConn.action.windowlessAction({ className: "IncidentManagement.Incident", key: "afc412f9-819b-4feb-81c3-30c7e0b9bf0e", actionName: "AssignToMe", onLoad: handleResult, onError: handleFail
});
action.attachDetachAction
Perform an attach or detach action.
Parameter properties:
- className: The name of the process object to perform the action against.
- key: The primary key (Guid) of the process record.
- actionName: The name of the attach or detach action to perform.
- linkedClassName: The name of the object for the record to attach or detach.
- linkedKey: The primary key (Guid) of the record to attach or detach.
- onLoad / onError: The functions to run on completion/failure.
webConn.action.attachDetachAction({ className: "IncidentManagement.Incident", key: "d811b3ec-8069-4490-8572-b44d1c1855e5", actionName: "AddChildIncident", linkedClassName: "IncidentManagement.Incident", linkedKey: "0c0ed95b-d1d2-455f-a17f-db5e192906fe", onLoad: handleResult, onError: handleFail
});
Version History
- 1.0.1: Fixed a glitch in the automatic explicit logon.
- 1.0: First release.
Disclaimer
Please read the LANDesk Share It Disclaimer