Calling Methods

In order to call any authenticated methods from a Web Service, the request must include a cookie in the HTTP header containing the FileHold Licensed Session Identifier with the cookie name FHLSID. The cookie represents the identity and permissions of the user performing the operation.

There are two special services in the API that do not require authentication: the Session Manager and Windows Login. Both services are a part of the User Role Manager application. A FHLSID is created by making a call to a Start Session method in one of these special services. A FHLSID can also be created with an OIDC call to an external identity provider get their FHLSID to authenticate which then works with the session manager to provide the session id and then looking for the FHLSID claim.

The three types of users FileHold uses the database to store local users and their securely hashed passwords. When a local FileHold user logs in, the Session Manager verifies the login and password in the database. When a domain user logs in, the Session Manager communicates directly with the appropriate domain controller to verify the identity of the user.

The Session Manager also verifies if the user has FileHold account enabled, whether the limit of concurrent session licenses for the server has been reached, etc. Finally a new session is created for the user and assigned a randomly generated globally unique identifier.

The FileHold service license determines the number of available full and limited concurrent session licenses. Some of the full licenses can be permanently assigned to users giving them guaranteed access to the system (for example, the system administrator). The remaining concurrent sessions are shared between all other users with an active FileHold account.

Each user with an active session takes one slot from the pool of concurrent sessions. A user can have simultaneous active full sessions with different client types, sharing one concurrent session slot. This makes it possible to use different client applications at the same time. When a new full session is created, the previous session for the given user and client type is automatically terminated. Limited sessions work a little differently. The same user can consume multiple limited sessions simply by logging in a second time. Limited sessions cannot be guarenteed.

All client types are reserved for exclusive use by FileHold except for the CustomClient. Anyone creating a custom application must use the CustomClient type. Failure to do so may result in incorrect operation of the system.

1
2
3

// Login with FileHold user name and password
SessionManager sessionManager = new SessionManager();
Guid sessionId = sessionManager.StartSession( username, password, Client.CustomClient );

// Login with FileHold user name and password        
client = new SessionManagerSoapClient(
    SessionManagerSoapClient.EndpointConfiguration.SessionManagerSoap,
       $"{protocol}://{hostName}/fh/filehold/UserRoleManager/SessionManager.asmx");
sessionResult = await client.StartSessionAsync( username, password, Client.CustomClient);
sessionId = sessionResult.Body.StartSessionResult;

# Login with FileHold user name and password
$sessionManagerProxy = New-WebServiceProxy -Uri $sessionManagerUri -Namespace UserRoleManager
$sessionId = $sessionManagerProxy.StartSession( $username, $password, [UserRoleManager.Client]::CustomClient.value__ )

sessionManager = Client(f'{base_url}/UserRoleManager/SessionManager.asmx?WSDL')
sessionId = sessionManager.service.StartSession(userid,password,'CustomClient')

The client application should store the FHLSID obtained from the Session Manager. Forms applications can use a simple variable and web applications may create their own cookie for verifying the user’s identity. The application can also retrieve additional information associated with the session, such as the name of the user and the list of operations which the user is allowed to perform.

1
2

// Get session information object for currently logged in user
SessionInfo sessionInfo = sessionManager.GetSessionInfo( sessionId );

Since the URLs of the web services are hard-coded in the configuration file of the client application and sometimes it’s necessary to allow the user to specify server’s URL at runtime, it may be necessary to replace the default URL of each web reference:

1
2
3
4
5
6
7
8
9

Uri absolutePath = new Uri( service.Url );
Uri relativePath = new Uri( baseServerUrl ).MakeRelativeUri( absolutePath );

string serviceUrl = serverUrl;
if ( !serviceUrl.EndsWith( "/" ) )
    serviceUrl += "/";

serviceUrl += relativePath;
service.Url = serviceUrl;

In order to pass the session identifier to the Web Service, it must be set as a cookie named FHLSID.

1
2
3
4
5
6
7
8
9
10
11

// If the service does not have cookie container create one
if ( service.CookieContainer == null )
    service.CookieContainer = new CookieContainer();

// Get the URI for which the cookie is valid
Uri uri = new Uri( service.Url );
string domain = uri.Host;
// Create the cookie
Cookie cookie = new Cookie( "FHLSID", sessionInfo.SessionId, "/", domain );
// Save the cookie for the service
service.CookieContainer.Add( cookie );

1
2
3
4
5
6
7
8
9
10
11
12

// Assume we will call the DocumentFinder
var dfClient = new DocumentFinderSoapClient(
    DocumentFinderSoapClient.EndpointConfiguration.DocumentFinderSoap,
    $"{protocol}://{hostName}/fh/filehold/LibraryManager/DocumentFinder.asmx");

using (new OperationContextScope(dfClient.InnerChannel))
{
    HttpRequestMessageProperty request = new HttpRequestMessageProperty();
    request.Headers["Cookie"] = $"FHLSID={sessionId}";
    OperationContext.Current.OutgoingMessageProperties[
        HttpRequestMessageProperty.Name] = request;
}

1
2
3
4
5

# Assume we will call the DocumentFinder
$documentFinderProxy = New-WebServiceProxy -Uri $documentFinderUri -Namespace LibraryManager
$documentFinderProxy.CookieContainer = New-Object System.Net.CookieContainer 
$cookie = New-Object System.Net.Cookie( "FHLSID", $sessionId, "/", $documentFinderUri.Host ) 
$documentFinderProxy.CookieContainer.Add( $cookie )

1
2

documentFinder = Client(f'{base_url}/LibraryManager/DocumentFinder.asmx?WSDL')
documentFinder.transport.session.headers.update({'Cookie': f'FHLSID={sessionId}'})

The default timeout for the web service calls may be too short for some operations so it can be set to a longer value.

1

service.Timeout = 18000;

By default the maximum allowed values are:

• Library Manager – 65000 s
• Document Repository – 180 s
• User Role Manager – 1800 s

If longer timeouts are required, the execution timeout for these services must also be increased in their configuration files, because the shorter of the two timeouts (client and server side) will cause the operation to fail.