/ws/client

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.

  • HTTP Authentication
    When using HTTP Authentication in the Browser, a prompt will ask the user for credentials. To prevent the 401 Authentication failed response, use the parameter 'no401' (http://localhost:7224/ws/client/createsession?no401).

  • Token Authentication
    Token Authentication is used to authenticate users without transmitting the password every time. A Login Token can be obtained with asnGetUserToken. The Token is transmitted either with a query parameter (http://localhost:7224/ws/client/createsession?token=aabbccddeeff) or as HTTP custom header (x-uctoken: aabbccddeeff). When using this option, no 401 response will be given. Failed Authentication will result in a 400 response with an json error struct.
    Replace aabbccddeeff with the login token:
    http://localhost:7224/ws/client/createsession?token=aabbccddeeff
  • Username and Password in query
    Username and Password may be transmitted as query parameters. When using this option, no 401 response will be given. Failed Authentication will result in a 400 response with an json error struct.
    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 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": "Invalid user name",
        "u8sFailedUser": ""
    },
    "error_value": 0,
    "invokedID": 44,
    "sessionID": "F157012E9D63824C80141E367C77659A"
}
400 Logon to UCServer failed (invalid passwd)
{
    "error": {
        "_type": "AsnLogonError",
        "iErrorDetail": 102,
        "sAuthCredetials": "",
        "u8sErrorString": "Invalid password",
        "u8sFailedUser": "user1"
    },
    "error_value": 0,
    "invokedID": 47,
    "sessionID": "3DF920177DF16F45909D8A7A5BFE9C19"
}

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: Open Page.;


<!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()
    {
      var serverurl = document.getElementById("serverurl").value;
      var ucsid = document.getElementById("ucsid").value;
      var user = document.getElementById("user").value;
      var pass = document.getElementById("pass").value;
      var func = 'createsession';
            
      var oXHR = new XMLHttpRequest();   // new HttpRequest instance
      oXHR.addEventListener("loadend", function(evt) {
        var outtext = oXHR.responseText;
        var 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
      
      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();    
    }
    function sendcommand()
    {
      var serverurl = document.getElementById("serverurl").value;
      var func = document.getElementById("func").value;
      var sessionid = document.getElementById("sessionid").value;
      var params = document.getElementById("params").value;
      try {
        JSON.parse(params);
      } catch(e) {
        document.getElementById("result").innerHTML = 'Failed: Params are not valid JSON: ' + e;
        return;
      }
      
      var oXHR = new XMLHttpRequest();   // new HttpRequest instance
      oXHR.addEventListener("loadend", function(evt) {
        var 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 6.1