Using the Connect Web Method

performs both the authentication and authorization operations, and ensures that the user is properly authenticated and belongs to the specified role request syntax frsheatintegrationconnectionresponse connect(string username, string password, string tenantid, string role) parameters username the login id for which the session is created the web method searches for the login id in the loginid column in the profile employee business object (profile table) password the user password this can be either an internal or external (active directory) password, depending on the employee record configuration tenantid the tenant for which the session is created the web method searches for the tenant id in the tenanturl field in the business object for the tenant in the configuration database (called configdb) the tenant record must be in the active state for the authentication to succeed role the role that the user logs in as return value frsheatintegrationconnectionresponse class, defined as follows public class frsheatintegrationconnectionresponse { public string connectionstatus; public string sessionkey; public string exceptionreason; } the frsheatintegrationconnectionresponse class has the following fields connectionstatus provides a status about the state of the connection the table below contains a full description of the available status values sessionkey the session key to use in all subsequent web service operations this field is only populated when the connectionstatus parameter has a value of success otherwise, the value is null exceptionreason contains exception information, if the application throws an exception when running this web method if the connect web method completes successfully, the application stores the session key in the corresponding member in the frsheatintegrationconnectiontresponse object exceptions if there is an error during the connect web method operation (either during the authentication or authorization phases), the server throws a soap exception and the web services client must handle the exception the following table lists the exceptions that can be encountered when executing the connect web method \<font color="#ffffff">soap exception\</font>\<font color="#ffffff">explanation\</font> action accessdenied either the specified user name does not exist in the tenant, or the password provided is invalid for the user name ensure that the credentials are correctly specified tenantnotfound either the specified tenant url cannot be found or the tenant is not currently in active status ensure that the tenant url is correct for accessing the tenant if it is, contact regarding the status of this tenant tenantinmaintenance the specified tenant is currently in maintenance mode confirm that the tenant is in maintenance mode if it is, contact about when the tenant will be set back to active status invalidrole either the specified role definition is not available in the tenant or the user is not currently associated with the specified role confirm that the role exists in the tenant and that the user belongs to the specified role sessionexpired the session key refers to a session that has expired this typically occurs when the api operation uses the session key from an earlier connect web method call and the session has expired due to inactivity execute the connect web method again to obtain a new session key if you use the same session key when running other web methods, you may run into authentication or authorization errors the web services client must account for the possibility of connection failures when running additional web methods example frsheatintegration frsvc = new frsheatintegration(); frsheatintegrationconnectionresponse connectresponse = frsvc connect(username, password, tenantid, role); if (connectresponse connectionstatus == "success") { } handling session expirations after making the initial call to the connect web method to obtain the session key, typically web service clients reuse the same session key value for subsequent web methods if the web services client is idle for longer than the session timeout value, the session expires and the session key is no longer valid after the session expires, if you try to use the expired session key again, the server returns a soap exception stating that the session has expired by throwing the explicit soap exception back to the client, the client can then use standard exception handling techniques for calling the connect web method again to obtain a new session key to use in subsequent web methods for net based web services clients, you can reference the frsheatintegration api by using either a web reference or a service reference the code to handle the soap exception differs slightly based on the type of reference the following code illustrates how this can be achieved, if the web services client is defined using a web reference to the frsheatintegration api objectquerydefinition query = new objectquerydefinition(); query select = new selectclass(); fieldclass\[] incidentfieldobjects = new fieldclass\[] { new fieldclass() { name = "incidentnumber", type = "text" }, new fieldclass() { name = "service", type = "text" } }; query select fields = incidentfieldobjects; query from = new fromclass(); query from object = "incident"; query where = new ruleclass\[] { new ruleclass() { join = "and", condition = "=", field = "incidentnumber", value = "10001" } }; frsheatintegrationsearchresponse searchresponse = null; try { searchresponse = frsvc search(authsessionkey, tenantid, query); } catch (soapexception soapexception) { if (soapexception actor == "sessionexpired") { connectresponse = frsvc connect(username, password, tenantid, role); if (connectresponse connectionstatus == "success") { authsessionkey = connectresponse sessionkey; searchresponse = frsvc search(connectresponse sessionkey, tenantid, query); } } } if (searchresponse != null && searchresponse status == "success") { webservicebusinessobject\[]\[] incidentlist = searchresponse objlist; foreach (webservicebusinessobject\[] incidentouterlist in incidentlist) { foreach (webservicebusinessobject incident in incidentouterlist) { console writeline("incident matches the selection criteria", incident fieldvalues\[0] value); } } } in particular, note the following code fragment try { searchresponse = frsvc search(authsessionkey, tenantid, query); } catch (soapexception soapexception) { if (soapexception actor == "sessionexpired") { connectresponse = frsvc connect(username, password, tenantid, role); if (connectresponse connectionstatus == "success") { authsessionkey = connectresponse sessionkey; searchresponse = frsvc search(connectresponse sessionkey, tenantid, query); } } } notice that the search web method operation is wrapped inside the try catch block if the soap exception occurs corresponding to the session expiration, review the actor property in the soap exception to determine if the connection error is due to the session timeout if the exception is due to the session timeout, the application invokes the connect web method again to obtain a new session key if the authsessionkey parameter is a globally accessible string, the application updates the session key property of the connect response object and you can run the search web method again the following code sample/example now illustrates this, if the web services client is defined using a service reference to the frsheatintegration api objectquerydefinition query = new objectquerydefinition(); query select = new selectclass(); fieldclass\[] incidentfieldobjects = new fieldclass\[] { new fieldclass() { name = "incidentnumber", type = "text" }, new fieldclass() { name = "service", type = "text" } }; query select fields = incidentfieldobjects; query from = new fromclass(); query from object = "incident"; query where = new ruleclass\[] { new ruleclass() { join = "and", condition = "=", field = "incidentnumber", value = "10001" } }; frsheatintegrationsearchresponse searchresponse = null; try { searchresponse = frsvc search(authsessionkey, tenantid, query); } catch (faultexception faultexception) { messagefault messagefault = faultexception createmessagefault(); if (messagefault actor == "sessionexpired") { connectresponse = frsvc connect(username, password, tenantid, role); if (connectresponse connectionstatus == "success") { authsessionkey = connectresponse sessionkey; searchresponse = frsvc search(connectresponse sessionkey, tenantid, query); } } } if (searchresponse != null && searchresponse status == "success") { webservicebusinessobject\[]\[] incidentlist = searchresponse objlist; foreach (webservicebusinessobject\[] incidentouterlist in incidentlist) { foreach (webservicebusinessobject incident in incidentouterlist) { console writeline("incident matches the selection criteria", incident fieldvalues\[0] value); } } } in particular, note the following code fragment try { searchresponse = frsvc search(authsessionkey, tenantid, query); } catch (faultexception faultexception) { messagefault messagefault = faultexception createmessagefault(); if (messagefault actor == "sessionexpired") { connectresponse = frsvc connect(username, password, tenantid, role); if (connectresponse connectionstatus == "success") { authsessionkey = connectresponse sessionkey; searchresponse = frsvc search(connectresponse sessionkey, tenantid, query); } } } notice that the search web method operation is wrapped inside the try catch block however, for service references, the exception that is caught is now a fault exception, and not the soap exception (as was the case with the earlier web reference) after the application catches the fault exception, it obtains the message fault review the actor property in the soap exception to determine if the connection error is due to the session timeout the example illustrates how to properly handle session expirations you can use the same technique for handling other kinds of exceptions, such as access denied, invalid role, and so on for example, for the access denied exception, the web services client might log the error locally to a log file or send an email to the administrator that the user name and password are not valid when used in the client