FRSHEATIntegration Web Service URL

the frsheatintegration web service can be accessed at a link similar to the example shown below https //\<tenantname>/serviceapi/frsheatintegration asmx replace \<tenantname> with the hostname corresponding to your particular tenant notice when accessing the above url, information is provided for the available web methods the corresponding wsdl file can be accessed at by adding “?wsdl” at the end of the previous url, as seen in the example link shown below\ https //\<tenantname>/serviceapi/frsheatintegration asmx?wsdl establishing the connection and role selection before an application can access a web service api on the saas platform, it has to be properly authenticated and authorized, with respect to the tenant this is achieved by first invoking the connect() webmethod, before performing any subsequent web service operations connect the connect webmethod is responsible for performing both the authentication and authorization operations, to ensure that the web service user is properly authenticated, and belongs to the specified role request syntax frsheatintegrationconnectionresponse connect(string username, string password, string tenantid, string role) parameters username loginid for which the session is to be created the loginid is searched against loginid column in the profile employee business object (profile table) password user password either internal or external (active directory) password can be used, depending on the employee record configuration tenantid tenant for which the session is to be created the tenant id is matched against the “tenanturl” field, in the tenants business object in the configdb database the tenant record must be in “active” state in order for authentication to succeed role the role that the indicated user will be logging in as return value an frsheatintegrationconnectionresponse object, defined as follows public class frsheatintegrationconnectionresponse { public string connectionstatus; public string sessionkey; public string exceptionreason; } the frsheatintegrationconnectionresponse class comprises the following fields connectionstatus – this field provides a status value indicating the state of the connection a full description of the available status values is provided in the table below sessionkey – the sessionkey which needs to be used in all subsequent web service operations this field will only be populated when the connectionstatus has a value of “success”, otherwise the value will be null exceptionreason – if there is an exception thrown in the course of running the connect webmethod, the exception information will be captured in this field if the connect webmethod operation completes successfully, the sessionkey will be stored in the corresponding member in the frsheatintegrationconnectionresponse object however, if there is an error encountered during the connect operation (either during the authentication or authorization phases), a soap exception will be thrown by the server, and the web services client will be required to handle the exception accordingly the following table lists the possible kinds of exceptions which can be encountered, while executing the connect webmethod \<font color="#ffffff">soap exception\</font>\<font color="#ffffff">explanation\</font> accessdenied either the specified username does not exist in the tenant, or the password provided is invalid for the username double check the credentials passed into the connect web method, to ensure that they are specified properly tenantnotfound either the specified tenanturl cannot be found, or that the tenant is not currently in “active” status double check the tenanturl to ensure that it is the correct url for accessing the tenant if the tenanturl is correct, please double check with frs operations regarding the status of the given tenant tenantinmaintenance the specified tenant is currently in maintenance mode confirm whether the tenant is in maintenance mode, and double check with frs operations, as to when the tenant will be set back to active status invalidrole either the specified role definition is not available in the tenant, or that the user is not currently associated with the specified role confirm whether the role actually does exist in the tenant, and that the user does belong to the given role sessionexpired the sessionkey refers to a session which has since expired this typically occurs when the api operation uses the sessionkey from an earlier connect webmethod call, and the session has expired due to inactivity whenever this occurs, it is necessary to execute the connect webmethod call again, so that a new sessionkey can be obtained, for performing any further actions this will be explained in the next section important note for all subsequent webmethods described in this document, the user may run into authentication / authorization errors, when reusing the same sessionkey value – the web services client will need to account for the possibility of connection failures, while exercising the remaining webmethods described in this document 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 webmethod to obtain the sessionkey, typically web service clients would reuse the same sessionkey value for invoking all subsequent webmethod operations, such as search, updateobject, etc if the web services client remains idle for a period of time, which exceeds the session timeout value that has been set for the tenant, the session will expire the sessionkey that was obtained earlier will no longer be valid once the session has expired, if the client tries to use the expired sessionkey for any subsequent operation (such as search), a soap exception will be returned by the server, alerting the client that the session has indeed expired by throwing the explicit soap exception back to the client, the client can then use standard exception handling techniques, for calling the connect webmethod again, to obtain a brand new sessionkey, which can then be used in subsequent operations for net based web services clients, the reference to the frsheatintegration api can be established 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 sample 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(authsessionkey, tenantid, query); } } } notice that the search webmethod operation is wrapped inside the try catch block if the soap exception occurs corresponding to the session expiration, the actor property in the soapexception can be inspected, to determine whether the connection error is due to the session timeout if the exception is due to the session timeout, it then goes ahead and invokes the connect webmethod again, to obtain a brand new sessionkey assuming that authsessionkey is a globally accessible string, it is now updated to the sessionkey property of the connectresponse object, and the search webmethod can be successfully run the second time the following code sample now illustrates how this can be achieved, 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); } } } again, notice that the search webmethod operation is wrapped inside the try catch block however, for service references, the exception that is caught is now a faultexception, and not the soap exception (as was the case with the earlier web reference) here, once the faultexception is caught, it is first necessary to obtain the messagefault from it from the messagefault, the actor property can then be the actor property can then be inspected, to determine whether the connection error is due to the session timeout the reconnect logic is then the same as the case for web reference based clients, as explained earlier the above example illustrates how to properly handle session expirations the same technique can be used for handling any other kinds of exceptions, such as accessdenied, invalidrole, etc for example, for the “accessdenied” exception, the web services client might log the error locally to a log file, or send an email to the administrator, alerting that the username / password is not valid, when used in the client getrolesforuser this web method retrieves a list of roles, which are available to the current web service user the response object returned from this webmethod, contains a field which stores an array of roles which are associated with the profile employee record of the current user request syntax frsheatintegrationgetrolesresponse getrolesforuser(string sessionkey, string tenantid) namedisplaypair\[] getrolesforuser(string sessionkey, string tenantid, string username) parameters sessionkey key received in the earlier connect request tenantid id of the tenant in question return value an frsheatintegrationgetrolesresponse object, defined as follows public class frsheatintegrationgetrolesresponse { public string status { get; set; } public list\<namedisplaypair> rolelist { get; set; } public string exceptionreason { get; set; } } the frsheatintegrationgetrolesresponse class is comprises the following fields status – this field provides a status value, indicating whether the webmethod was able to successfully retrieve the list of roles for the current user assuming the sessionkey (returned from the previous connect webmethod call) is valid, this field should return a value of “success” under most circumstances rolelist – contains an array of namedisplaypair objects each namedisplaypair entry corresponds to a role which the current user belongs to for each namedisplaypair record in the array, the name property returns the name of the role, whereas the displayname property returns the displayname of the role exceptionreason – if there is an exception thrown in the course of running the getrolesforuser webmethod, the exception information will be captured in this field example frsheatintegrationgetrolesresponse getrolesresponse = frsvc getrolesforuser(authsessionkey, tenantid); namedisplaypair\[] rolepairlist = null; if (getrolesresponse status == "success") { rolepairlist = getrolesresponse rolelist; console writeline("the current user belongs to the following roles "); foreach (namedisplaypair rolepair in rolepairlist) { console writeline("\trole => displayname \\" \\"", rolepair name, rolepair displayname); } }