The client route is used to establish a user session with event notifications.
First Steps
The first step is to create the user session. Use a UCServer user name and password to authenticate. The result will be a json Object that contains the sessionid.
POST /ws/client/createsession
X-no401: "1"
X-ucsid: "local"
X-simple: "1"
{
}
200 OK
{
"sessionid": "470977D3647E174DB9AF9A0C3567A3E7"
}
Authentication options
There are different authentication options available.
Replace aabbccddeeff with the login token:
http://localhost:7224/ws/client/createsession?token=aabbccddeeff
Replace username and password with valid credentials:
http://localhost:7224/ws/client/createsession?user=username&pass=password
Error Conditions
There are different error coditions and corresponding error messages.
HTTP Code | Description | Result Body |
---|---|---|
502 | invalid UCSID or UCServer is not connected here |
{ "error": { "details": "server not connected here: [local1]", "_type": "WsError", "iErrorDetail": 119, "u8sErrorString": "UCServer is not connected here" } } |
400 | Logon to UCServer failed. For iErrorDetail Values see AsnLogonErrorEnum. |
{ "error": { "_type": "AsnLogonError", "iErrorDetail": 101, "sAuthCredetials": "", "u8sErrorString": "User Authentication failed", "u8sFailedUser": "" }, "error_value": 0, "invokedID": 44, "sessionID": "F157012E9D63824C80141E367C77659A" } |
Using Javascript
You may Javascript to send commands to the server. Copy the following text to a html file and open it in the browser.
You may also open the page here.
<!DOCTYPE html>
<html>
<style>
span { vertical-align: top; display: inline-block; width: 200px; }
input { display: inline-block; width: 400px; }
</style>
<body>
<form>
<span>Server URL:</span><input id="serverurl" value="http://localhost:7224"/><br/>
<span>UCSID:</span><input id="ucsid" value="local"/><br/>
<span>Username:</span><input id="user" value=""/><br/>
<span>Password:</span><input id="pass" value=""/><br/>
<button type='submit' onclick='createsession(); event.preventDefault();'>Create Session</button><br/>
</form>
<form>
<span>SessionID:</span><input id="sessionid" value=""/><br/>
<span>Function:</span><input id="func" value="asnGetLoggedInContact"/><br/>
<span>Params:</span><textarea rows="7" id="params">{ }</textarea><br/>
<button type='submit' onclick='sendcommand(); event.preventDefault();'>Send Command</button><br/>
</form>
<pre id="result"></pre>
</body>
<script>
function createsession()
{
let serverurl = document.getElementById("serverurl").value;
let ucsid = document.getElementById("ucsid").value;
let user = document.getElementById("user").value;
let pass = document.getElementById("pass").value;
let func = 'createsession?clientappid=15'; // since ProCall 7 you have to tell the server your application type (Web = 15)
let oXHR = new XMLHttpRequest(); // new HttpRequest instance
oXHR.addEventListener("loadend", function(evt) {
let outtext = oXHR.responseText;
let response = {};
try {
response = JSON.parse(oXHR.responseText);
outtext = JSON.stringify(response, null, 4);
} catch(e) {
}
if (oXHR.status == 0) {
document.getElementById("result").innerHTML = 'Failed: General Network Error';
} else if (outtext == '') {
document.getElementById("result").innerHTML = 'Failed: No response received';
} else if (oXHR.status == 200) {
document.getElementById("result").innerHTML = outtext;
if (response.hasOwnProperty('sessionid')) {
document.getElementById("sessionid").value = response.sessionid;
}
} else {
document.getElementById("result").innerHTML = outtext;
}
});
//epid must be unique for every createsession request
// for ProCall 7 it is a MUST to tell the server the API Version ('70' for ProCall 7, '61' for ProCall 6)
// for ProCall 6 you can (and SHOULD) do it.
let apiVersion = 70;
oXHR.open("POST", serverurl + "/ws/client/" + func, true);
oXHR.setRequestHeader("Authorization", "Basic " + btoa(user + ":" + pass));
oXHR.setRequestHeader("Content-Type", "application/json;charset=utf-8");
oXHR.setRequestHeader("X-no401", "1");
oXHR.setRequestHeader("X-ucsid", ucsid);
oXHR.setRequestHeader("X-simple", "1");
oXHR.send('{ "negotiate": { "iClientProtocolVersion": '+apiVersion+' } }');
}
function sendcommand()
{
let serverurl = document.getElementById("serverurl").value;
let func = document.getElementById("func").value;
let sessionid = document.getElementById("sessionid").value;
let params = document.getElementById("params").value;
try {
JSON.parse(params);
} catch(e) {
document.getElementById("result").innerHTML = 'Failed: Params are not valid JSON: ' + e;
return;
}
let oXHR = new XMLHttpRequest(); // new HttpRequest instance
oXHR.addEventListener("loadend", function(evt) {
let outtext = oXHR.responseText;
try {
outtext = JSON.stringify(JSON.parse(oXHR.responseText), null, 4);
} catch(e) {
}
if (oXHR.status == 0) {
document.getElementById("result").innerHTML = 'Failed: General Network Error';
} else if (outtext == '') {
document.getElementById("result").innerHTML = 'Failed: No response received';
} else if (oXHR.status == 200) {
document.getElementById("result").innerHTML = outtext;
} else {
document.getElementById("result").innerHTML = outtext;
}
});
oXHR.open("POST", serverurl + "/ws/client/" + func);
oXHR.setRequestHeader("Content-Type", "application/json;charset=utf-8");
oXHR.setRequestHeader("X-ucsessionid", sessionid);
oXHR.setRequestHeader("X-ucsid", ucsid);
oXHR.send(params);
}
</script>
</html>
All API endpoints may be called with GET or POST. Jsonp is supported.
Version 7