Skip to main content

Link Generator Installation Guide

Raise a support ticket

DISCLAIMER​

Any advice FYB provide in relation to setting up any FYB App, FYB Add-in, FYB Connector and or advice in relation to opening access to your on-premises or in the cloud systems will be general advice only. This means that the advice is of a general nature and will not take into account your network setup, network infrastructure or any security requirements that you may have or in fact need. It is highly advised that you seek advice from internal or external providers to ensure that they are comfortable with what is required prior to going ahead with any deployment, setup or configuration for external access.

LICENSE DETAILS​

LINK GENERATOR API v9.0.x and above Licensing

A .NET Core license must be used for the API. You can request one by reaching out to membershub@fyb.com.au

Please contact FYB for a valid license if you are yet to obtain one for your Add-in.

INSTALLATION COMPONENTS​

The following installation components are required to ensure full functionality of the FYB Link Generator:

  • FYB Link Generator API allows web links to be generated. This is a server-side installation.
  • FYB Link Generator Add-In allows the interface to be accessed by users and the Admin Console to be accessed by Administrators. This is a server-side configuration.
  • FYB CM Launcher allows desktop links to be generated. This is a client-side installation.
Note

The FYB Link Generator API needs to be installed first.

LICENSE​

  1. Create a folder to house the license file (.lic) on the IIS Server

  2. Place the license file in this folder

    Note

    You will be asked to enter this location during the installation

TRUSTED USER ACCOUNT​

Add the account that will run the application pool as a Trusted User Account in Enterprise Studio.

Please refer to your Enterprise Studio help file on adding trusted accounts. If using a system account (application pool identity, network service etc) you will be required to enter the details as DOMAIN\ServerName$

If using a dedicated windows service account, you will be required to enter the details as DOMAIN\username.

PREREQUISITES INSTALLATION​

Warning

Before running the MSI ensure that all prerequisites are complete. Including deploying the .NET 10 SDK and Hosting Bundle and installing IIS URL Rewrite.

.NET 10 SDK AND HOSTING BUNDLE​

To deploy the Net Core SDK and Hosting Bundle to the server, follow these steps:

  1. Install the latest .NET 10 SDK (x64) found here

    Image

  2. Install the latest ASP.NET Core 10 Runtime Hosting Bundle found here

    Image

  3. Once both executables have been installed, complete a full server restart to allow for .NET 10 to bind to IIS. If a server restart is not possible an IIS reset can be completed with the following CMDs from an elevated command prompt.

    • net stop was /y
    • net start w3svc
    • iisreset
    Note

    To check that the SDK has been attached to the hosting bundle, open Command Prompt and type dotnet --info

    Image

INSTALLATION​

The FYB Link Generator API MSI will:

  • Deploy the installation files
  • Setup the application pool and application in IIS
  • Setup the temp folder
  • Configure the Link Generator API as specified by the user

To install the Link Generator API, follow these steps:

  1. Run command prompt as an administrator and launch the linkgeneratorapi-xxx.msi

    NOTE

    You must run the linkgeneratorapi-xxx.msi as a user that has permission to validate user credentials

  2. Click on the Next button

    apimsi1.png

  3. On the Web Application Settings screen, select a Site to host the application and enter a name for the Virtual Directory

    Note

    A HTTPS site must be selected. The virtual directory name must remain as LinkGeneratorAPI and it cannot be renamed.

    IIS Directory

    The application must be installed under the dedicated site as an application. It cannot be installed at the site level

    image.png

  4. Click on the Next button

    image.png

    Note

    You can use an existing virtual directory or create a new one with the installer.

  5. On the Application Pool Settings screen, enter the domain, username and password for the Application Pool identity

  6. Click on the Next button

    image.png

    NAMEDESCRIPTION
    Domain for Application PoolThe domain name for the application pool identity
    Username for Application PoolThe Username for the application pool identity
    Password for Application PoolThe Password for the application pool identity
    Use Default Application Pool IdentityUtilize the default application pool identity
  7. On the Configuration Settings screen, enter the dataset ID, cmserverapiurl, license path and temp path

  8. Click the Next button

    image.png

    Note

    • You can use an existing folder for the Temp Path or create a new one with the installer

    NAMEDESCRIPTION
    Dataset IDThe two-character dataset identifier
    Workgroup Server NameThe Content Manager Workgroup Server Name used for the connection to the dataset. Database connection can be made using the workgroup server name or URL.
    Workgroup Server URLThe Content Manager Workgroup URL used for the connection to the dataset. Database connection can be made using the workgroup server name or url.
    License PathThe local path of the Link Generator license file, including ".lic"
    Temp PathThe local path of the folder that the Link Generator API is to use for temporary file storage.
  9. If your environment is configured to only allow Open Id authentication (e.g. Azure AD or ADFS) for your Content Manager, you'll receive the following message; If this is not applicable, skip to step 9.

    image.png

  10. Click OK to navigate to the Open Id Settings screen and enter the required values.

    image.png

    Note

    Please refer to the below guides on how to configure the Confidential Client App and Trusted User:

    NAMEDESCRIPTION
    Client IdThe Client/App Id of the Open Id application used to secure Content Manager. For ADFS authentication, this will be the username of the Confidential Client app.
    Client SecretThe Client/App Id of the Open Id application used to secure Content Manager. For ADFS authentication, this will be the password of the Confidential Client app.
    Trusted UserThe Network Login value of the Content Manager Confidential Client app location. For ADFS authentication, this will be the username of the Confidential Client app.
  11. On the Authentication Settings screen (Optional) , if you require the use of explicit authentication, select the Explicit Authentication checkbox and input the authentication credentials to be used by Link Generator API, then click Next. If not required, Click Next without filling out the credentials.

    Should I use Explicit Authentication?

    Explicit Authentication will allow for a dedicated account to be used for ALL connections to the dataset for Link Generator. This is best utilised for externally exposed Link Generators, as it will allow for users who not not have a Content Manager account to access Link Generator links.

    The account nominated for use should have the appropriate security settings enabled to ensure only selected data is exposed using this account.

    image.png

  12. On the Destination Folder screen select the install location and click the Next button

    msi4.png

  13. From the Confirm Installation window click on the Install button

    apimsi6.png

  14. The installation will commence

    apimsi7.png

  15. Once the installation is complete click on the Finish button

    apimsi8.png

COMMAND-LINE ARGUMENTS (OPTIONAL)​

The following command-line arguments can be passed to the MSI if required.

ARGUMENTPURPOSE
DBIDSets the Database ID that connects to Content Manager dataset to run the application
WORKGROUP_SERVERSets the workgroup server name that connects to Content Manager
WORKGROUP_SERVER_URLSets the workgroup server URL that connects to Content Manager
LICENSE_PATHSets the license that connects to the application
TEMP_PATHSets the temp path that connects to the application
WEB_APP_POOL_IDENTITY_DOMAINSets the App Pool domain for the application pool
WEB_APP_POOL_IDENTITY_NAMESets the App Pool username for the account running the application pool. Use "" around the username if there are any special characters
WEB_APP_POOL_IDENTITY_PWDSets the App Pool password for the account running the application pool. Use "" around the username if there are any special characters

CONFIGURATION​

  1. After the installation process is complete, you will be able to locate the application installed within the site selected during installation

    image.png

  2. From the Features View go to Authentication and ensure that Windows Authentication is the only authentication types enabled

    image.png image.png

  3. Right click the application in IIS and select the explore option

    app.jpg

  4. Right click the app data folder and select properties

    prop.jpg

  5. Navigate to the security tab and ensure users have read, write and modify permissions

    permiss.jpg

  6. Click on Application Pools

    image.png

  7. Within the application pool listing screen, right click on Link Generator API application pool and select the Advanced Settings option from the drop-down menu

    image.png

  8. Within the Advanced Settings window, set Start Mode to AlwaysRunning, Idle Time-out Action to Suspend and Idle Time-out Action (minutes) to 0

    App Pool Setting.jpg

  9. Click on the OK button

  10. Select the LinkGeneratorAPI application in IIS and navigate to its Advanced Settings

    image.png

  11. Set Preload Enabled to True and click on the OK button

    image.png

INSTALLATION​

  1. Create an FYB Add-ins folder on the Content Manager workgroup server

    image.png

  2. Right click on the FYB Add-ins folder > Properties > click on the Sharing tab

    image.png

  3. Click on the Advanced Sharing button

    image.png

  4. In the Advanced Sharing window, tick ‘Share this folder’ and remove the space between FYB and Add-ins, then add a ‘$’ sign which will keep the folder hidden

    image.png

  5. Click on the Permissions button

  6. Give Everyone the Full Control permission

    image.png

  7. A Network Path will now be available

  8. Create a subfolder inside the FYB Add-ins folder to house the license file (.lic) on the server.

    Note

    If there is a pre-existing license folder use that instead.

  9. Place the license file in this folder

    Note

    Note down the path to the license file, you will be asked to enter it later during the install.

  10. Run command prompt as an administrator and launch the linkgenerator-xxx-32bit/64bit.msi

  11. Click the Next button

    msi1.png

  12. On the Configuration Settings screen, enter the shared path for the license (including file name), shared path for the temp path and the dataset ID.

  13. Click on the Next button

    Link Gen Config.png

    NAMEDESCRIPTION
    Dataset IDThe two-character dataset identifier
    Workgroup Server NameThe Content Manager Workgroup Server Name used for the connection to the dataset. Database connection can be made using the workgroup server name or URL.
    Workgroup Server URLThe Content Manager Workgroup URL used for the connection to the dataset. Database connection can be made using the workgroup server name or url.
    License PathThe shared path to your license file, including the ".lic"
    Temp PathThe shared path to the temp path for Link Generator
  14. If your environment is configured to only allow OpenId authentication (e.g. Azure AD or ADFS) for your Content Manager, you'll receive the following message:

    image.png

    Note

    If you have not already, please ensure you are using a Workgroup Server URL not the Workgroup Server Name for the connection defined on the previous screen

  15. Click OK to navigate to the Open Id settings screen and enter the required values.

    image.png

    Note

    Please refer to the below guides on how to configure the Confidential Client App and Trusted User:

    NAMEDESCRIPTION
    Client IdThe Client/App Id of the Open Id application used to secure Content Manager. For ADFS authentication, this will be the username of the Confidential Client app.
    Client SecretThe Client/App Id of the Open Id application used to secure Content Manager. For ADFS authentication, this will be the password of the Confidential Client app.
    Trusted UserThe Network Login value of the Content Manager Confidential Client app location. For ADFS authentication, this will be the username of the Confidential Client app.
  16. On the Configuration Settings (Continued) screen, select the default link format, enter URLs for internal, external, and web client links, and set whether or not to use thumbnail icons

  17. Click on the Next button

    image.png

    NAMEDESCRIPTION
    Default Link FormatSet the default link format to show when Link Generator opens. This can be set to "URL, "HYPERLINK", or "HTML".
    InternalFYB Link Generator API URL configured for internal use
    Example: https://internal/LinkGeneratorAPI
    ExternalFYB Link Generator API URL configured for external use if applicable.
    Example: https://external/LinkGeneratorAPI
    If externally accessible links are not being used, leave this field empty.
    Web ClientThe Content Manager Web client URL
    Example: https://server/ContentManager?q=uri:
    To disable the Web Client link, leave this field empty
    Thumbnail IconTo display file type icon thumbnails for Word or email hyperlinks, tick the check box.
  18. On the External Link Setup (Optional) screen, enter the Link Name, Folder Path and Record Type URIs

  19. Click on the Next button

    image.png

    NAMEDESCRIPTION
    Link NameSet the name of the External Link to be configured within CM. This will determine the default name of the button used to launch Link Generator
    Example: FYB Link Generator
    Folder PathThe network share path from which Link Generator will be accessed
    Example: \server\fybaddins$\Link Generator\
    Record Type URIsSet the Record Types you would like Link Generator to be available to use on.
  20. On the Destination Folder screen, select the install location, this should be set to the shared FYB Add-ins folder created earlier in this guide

    2021-11-23_9-50-53.jpg

  21. On the Confirm Installation window, click on the Install button

    msi5.png

  22. The installation will commence

    msi6.png

  23. Click on the Finish button

    msi7.png

COMMAND-LINE ARGUMENTS (OPTIONAL)​

The following command-line arguments can be passed to the MSI if required.

ARGUMENTPURPOSE
DBIDSets the Database ID that connects to Content Manager dataset to run the application
LICENSE_PATHSets the license that connects to the application
FORMATSet the default link format to show when Link Generator opens. Value selected can be HTML, HYPERLINK or URL
INTERNALURLFYB Link Generator API URL configured for internal use
EXTERNALURLFYB Link Generator API URL configured for external use if applicable
WEBCLIENTURLThe Content Manager Web client URL

CONFIGURATION​

warning

These steps can be skipped if installation was completed by the MSI, and only to be used for Record links. If you wish to utilize Link Generator with Locations, complete the steps below.

CREATING THE EXTERNAL ICON​

  1. Open Content Manager and click on Tools> Administration > External Icons

  2. Right Click, and select New External Icon

  3. Enter the Name as Link Generator Icon

  4. Enter the File Name by selecting the Link Generator.ico from the installation path of the Link Generator External Link.

    image.png

  1. Open Content Manager and click on Tools > Administration > External Links

  2. Right Click, and select New External Link

  3. From the external link type list, select External executable, click OK

  4. Enter the Link Name as FYB Link Generator

  5. Select the Link Generator Icon from the Icon dropdown

  6. Under ‘Folder or Subfolder’, enter the Network Location of the FYB Add-ins\Link Generator folder created earlier in the guide

  7. Under Executable File Name browse to the Link Generator folder and select

    image.png

  8. Check Link supports tagged processing

  9. Under Command line parameters when doing tagged processing enter ^!Objecttype^ ^!Urilist^

  10. Check Use tagged command line format for single selection

    image.png

  11. Select the Usage (Record) tab

  12. Tag each of the appropriate record types.

    image.png

  13. Select the Usage (Location) tab

  14. Tag each of the appropriate location types.

    image.png

  15. Click on the OK button

  16. The Add-In has now been deployed

INSTALLING CM LAUNCHER​

The FYB CM Launcher needs to be installed on each users’ machine. CM Launcher is required by the Link Generator to perform native functions on the user’s machine such as open Content Manager or open a record for editing.

To install the CM Launcher, follow the install guide here

To uninstall FYB Link Generator API using the MSI please follow the steps below:

  1. Launch linkgeneratorapi-xxx.msi.

  2. The Link Generator API uninstallation window should appear, click Next.

    apimsiu1.png

  3. Click on the Remove button

    apimsiu2.png

  4. On the next screen, click on the Remove button

    apimsiu3.png

  5. The application uninstallation process will commence

    apimsiu4.png

  6. Click on the Finish button to remove complete the removal process

    apimsiu5.png

To uninstall FYB Link Generator using the MSI please follow the steps below:

  1. Launch the linkgenerator-xxx-32bit/64bit.msi

  2. The Link Generator uninstallation window should appear, click Next.

    msiu1.png

  3. Click on the Remove button

    msiu2.png

  4. On the next screen, click on the Remove button

    msiu3.png

  5. The application uninstallation process will commence

    msiu4.png

  6. Click on the Finish button to complete the removal process

    msiu5.png

  1. Open Content Manager and click on Tools > Administration > External Links

  2. Right click the FYB Link Generator external link and click on the Remove button

    image.png

  3. The external link will be removed from Content Manager