Tutorial: Configuring wMobile Virtual File System (VFS)
Virtual File System (VFS) allows wMobile to handle files spread over your local area network, exempting the users from the concern of authentication. In this article we'll show you how to configure wMobile Virtual File System (VFS) in order to access your GoldMine files including linked documents, attachments and reports.
VFS is a repository of Servers, Shares and Folders for which we can define credentials. For Shares and Folders we can also define mapped drives. Servers, Shares and Folders in the context of VFS are called VFS Objects and they can be referred by UNC paths.
The VFS engine is part of Remote GoldMine Service and it provides functionality related to:
1. Mapped drive translation: given a path that contains a mapped drive, VFS will replace the mapped drive with the associated UNC path. For instance, a path like Z:\MyDocument.pdf will be translated to \\Server1\data\MyDocument.pdf, if Z is mapped to \\Server1\data
2. Authentication: when a UNC path like above is about to be accessed, the VFS will check if there are any defined credentials for the last VFS object in the path or any of its ancestors (parent directories). If that’s the case, VFS will perform a login using those credentials before the file in the path is accessed and a logout after the file is processed (read, written).
Note: The VFS engine does not check for windows authorization (i.e. permissions) on folders and shares, so you have to make sure that the share and NTFS permissions are appropriate for the type of access you need. See more below in VFS and Windows Permissions.
How does it work?
Let's assume we have the following LAN layout, depicted in Figure 1:
- Server1 that has a share, data, mapped to a drive Z. It is used as a data server and it stores documents.
- Server2 is the GoldMine Server, where GoldMine and Remote GoldMine Service reside. GoldMine is installed in the apps folder which is located in a share called shared. The apps folder is mapped as W drive. GoldMine SysDir is defined as W:\GoldMine
- wMobile is installed on a Web Server, different than Server1 and Server2. We’ll need to access both, Server1 and GoldMine folder on Server2, for linked documents, email attachments or reports.
- The figures below shows how we defined the corresponding VFS objects in wMobile Manager Console:
1. Server1 - server object with access credentials (RemoteUserName and RemoteUserPassword are set). The UNC path for this object is \\Server1
2. data – a share on Server1 server mapped to drive letter Z. The UNC path for this share is \\Server1\data. It will be accessible also as Z:
3. Server2 – another server in the LAN. No credentials have been defined for this server.
4. shared – a share on Server2. UNC path for this object is \\Server2\shared
5. apps – a remote folder mapped to a drive letter W. UNC path for this object is \\Server2\shared\apps. It will be accessible also as W:
Note: For more information about managing VFS objects (Servers, Shares, Folders) in wMobile Manager Console, please visit check out the online help.
Now, let’s check out what happens when a wMobile user tries to download a GoldMine linked document with the path: Z:\MyDocument.pdf
First, wMobile will forward the request to Remote GoldMine Service, which will use the VFS to read that document.
Initially, the VFS will try to translate the Z drive to a UNC path. According to the Figure 3, Z is defined as \\Server1\data, so the path will become \\Server1\data\MyDocument.pdf.
Next, the VFS engine will decide if it needs to perform authentication on Server1 in order to download the file. In order to take that decision, the VFS will iterate through all VFS objects in the path, bottom-up, and if it finds one that has a set of credentials (RemoteUserName, RemoteUserPassword) it will use those credentials to authenticate against Server1.
In this case we only have two: Server1 and data. The search will be performed bottom up, so from data to Server1 and because the Server1 has credentials assigned, the read file operation will be performed after the VFS will login to Server1 using the credentials from Figure 4. After the file is transferred, a logout request will be performed.
Figure 8, below, shows us the flow for this process:
When we configure a folder or share object in VFS we have to be aware of the user account that VFS will use to access that object. When there are credentials set for that VFS object or one of its ancestors, the user specified by those credentials will be used to access the files in the VFS object.
If there are no credentials defined for a VFS object, the following rule applies:
1. If Remote GoldMine Service is running as Local System. VFS will try to access all files using the RGMSUser account, created when the Remote GoldMine Service was installed. This account is not a privileged account. It is just a member of Users group on the Remote GoldMine Service computer.
2. If Remote GoldMine Service is running as specific Windows user. In this case, VFS will operate as that user under which the service runs.
So, the VFS Account is the account under which VFS performs the file access operations (read, write). This could be: the user account defined on the closest VFS ancestor (parent directory) of the file, the RGMSUser or a specific Window user.
Note: When you want to set credentials for a specific share or folder, it’s recommended to set them at server level. The credentials will be inherited by default, to all shares and folders defined for that server.
VFS takes care of authentication, but it does not check for authorization (i.e. permissions). Make sure that the VFS Account Share Permissions & NTFS Permissions combination will allow read/write access on the target file. In this case the following rule applies:
When you combine shared folder permissions and NTFS permissions, the more restrictive permission is always the overriding permission.
For more details about Share and NTFS permissions read this article .
If we want to view the file mentioned in the initial scenario: Z:\MyDocument.pdf in the following context:
- Remote GoldMine Service is running as Local System
- Z is mapped to \\Server1\data, see Figure 5
- Credentials are set for Server1, RemoteUserName =user1, see Figure 4
The process will flow as below:
1. Z is translated to \\Server1\data and the path becomes \\Server1\data\MyDocument.pdf
2. Credentials are required for
\\Server1\data\MyDocument.pdf path, because we have defined them on Server1 and they are inherited. So, the VFS will try to access the file as user user1. The account user1 must meet the following conditions in order for this operation to succeed:
a. It must be an account on Server1 or member of a User group defined on Server1
b. user1 NTFS permissions on D:\data must include Read and Modify
c. user1 Share Permissions must include Change and Read. This can be done explicitly as you can see below:
or you can grant Modify permission to Everyone or to a specific group that includes user1
3. If the above conditions are met the file is transferred to the browser and the user will be able to see it. Otherwise, the user will receive an Access Denied error message and detailed log entry will be added to the Remote GoldMine Service log.
Usually, the GoldMine files are on the same machine as GoldMine and Remote GoldMine Service but they are referred through a mapped drive based path or UNC path. In this case it is not necessary to add entries in VFS, but you need to make sure that the RGMSUser has the appropriate NTFS and Share Permissions on the shared folder that contains the documents.
Let’s assume that a user wants to file an email in wMobile that has an attachment called MyAttachment.pdf, in the following context:
1. Remote GoldMine Service is running as Local System
2. GoldMine SysDir is defined as W:\GoldMine
3. GoldMine stores attachments in SysDir\Mailbox\Attach which actually is W:\GoldMine\Mailbox\Attach
4. W maps to \\Server2\shared\apps. See Figure 2 and Figure 6.
5. There are no credentials defined on VFS objects in the path \\Server2\\shared\apps
wMobile will perform the following operation in order to upload the file to Mailbox\Attach folder:
1. The full path of the attachment will be determined and in this case it will be W:\GoldMine\Mailbox\Attach\MyAttachment.pdf.
2. VFS will try to upload the file in the W:\GoldMine\Mailbox\Attach folder without performing any authentication because there are no credentials defined for any VFS object in the path. In this case, the operation will be performed using the RGMSUser account. In order for the upload operation to succeed, we’ll need to make sure that RGMSUser NTFS and Share Permissions on D:\shared\ include Modify and Read.
3. If the above conditions are met the file will be uploaded successfully. Otherwise, the email will not be filed, and a detailed log entry will be added to the wMobile log and Remote GoldMine Service log.
What should we add to VFS configuration?
In order to determine what objects you have to add to your VFS configuration, you need to know the possible locations for the following GoldMine files:
- Linked Documents
- Mail Attachments
If you have such files that point to a UNC path, you need to make sure that RGMSUser can access those files or you should add those paths to VFS and set the appropriate credentials and mapped drives. Another option will be to run Remote GoldMine Service account under a specific Windows account that has access to all GoldMine files.
wMobile Manager Console helps you start with VFS configuration, by providing an option called ‘Select Linked Document Folder Paths’ that will scan all Contsupp table entries for linked document paths that begin with a \\ServerName. So it scans for UNC paths. If such paths are found, wMobile Manager Console will recommend you to import them in VFS. If you decide to do so, you may want to go ahead and set the required credentials on these paths.
If you are aware of other path or/and mapped drives you are using with GoldMine, please add them in VFS.
So, we need to add objects in VFS in the following cases:
1. We have paths that contain mapped drives.
2. We have paths that refer to network shares/folders that cannot be accessed by the RGMSUser if Remote GoldMine Service is running as Local System or they cannot be accessed by the Remote GoldMine Service account, if that account is a normal Windows account.
VFS Objects Reference
A Server represents a computer in the local area network that shares one or more resources (folders, drives) to the network.
|Type||The Type will be Server|
|Name||A valid Server name|
|Path||The UNC path of the server. Its defines as \\Name where Name is the server name|
|RemoteUserName||A UserName that can access the server|
|RemoteUserPassword||The password for the above user|
In this context a share is a file system folder that has been made available from one host to other hosts on your local area network.
|Type||The Type will be Share|
|Name||A valid Share name|
|Path||The UNC path of the share|
|RemoteUserName||A UserName that can access the share|
|RemoteUserPassword||The password for the above user|
|MappedDrive||One or more drive letters associated with the Share path|
In this context, it’s a file system folder that is part of an UNC path.
|Type||The Type will be Folder|
|Name||A valid Folder name|
|Path||The UNC path of the folder.|
|RemoteUserName||A UserName that can access the folder|
|RemoteUserPassword||The password for the above user|
|MappedDrive||One or more drive letters associated with the folder path|
We hope you've enjoyed this tutorial on Configuring wMobile Virtual File System (VFS). For any questions, leave us a message here, and we'll be happy to answer!