Skip to main content

Service2CM Installation Guide

Raise a support ticket

DISCLAIMER​

Any advice FYB provides 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 consider 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​

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 the full functionality of the FYB Service2CM:

  • FYB Service2CM connector - this is a server-side installation

INSTALLING FYB SERVICE2CM​

LICENSE​

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

  2. Place the license file in this folder

    Note

    Please be aware 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 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.

INSTALLATION​

BREAKING CHANGES

Note that this version of Service2CM (v2) is a major update and is not backwards compatible with previous versions.

To preserve existing connections a backup of your current version must be taken and existing connections will need to be re-imported via the admin console after installation is complete.

You should complete a full uninstall of the previous version before installing this version. The uninstall steps can be found in the relevant versions installation guide.

You will also need to obtain a new license type from FYB if upgrading to this version. Previous license files will not work even if they have not expired.

Warning

Before running the MSI ensure that all prerequisites are complete. Including deploying the .NET 7 SDK and Hosting Bundle.

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

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

    MicrosoftTeams-image.png

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

    image.png

  3. Once both executables have been installed, complete a full server restart to allow for .NET 7 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.png

The Service2CM MSI will:

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

To install the Service2CM Application, follow these steps:

  1. Run command prompt as an administrator and launch the service2cm.msi

  2. Click on the Next button

    image.png

  3. On the Web Application Settings screen select the HTTPS protected site (recommended) to host the applicationand click on the Next button

    Note

    The virtual directory name must remain as Service2CM 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

    image.png

  4. On the Application Pool Settings screen (below), enter the domain, username, and password for the Application Pool identity. Click the Next button

    image.png  

  5. On the Configuration Settings screen enter the required information. Further details are in the table below.

  6. Click on the Next button

    image.png

    FIELDDESCRIPTION
    Dataset IDContent Manager two-character dataset identifier
    Workgroup Server NameContent Manager workgroup server name. The workgroup server name or workgroup URL can be utilised to establish a dataset connection.
    Workgroup Server URLContent Manager workgroup server URL. The workgroup server name or workgroup URL can be utilised to establish a dataset connection.
    License PathLocal path to Service2CM license file
    Temp PathLocal temporary directory used by the application to cache content manager documents. Please include the trailing slash, for example: C:\FYB Add-Ins\Service2CM\
  7. 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

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

    image.png

    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.
    Note

    A designated CM Location is required to be nominated as the Trusted User. The CM Location will require the following permissions:

    • Record Update Permissions
      • Create Records
      • Modify Records
      • Extract Document
      • Append To Existing Notes
      • Update Document
      • Modify Record Additional Field Values
  9. On the ServiceNow Settings screen, enter the following fields: Ensuring the Connected App Set up guide has been completed prior to completing these settings.

image.png

FIELDDESCRIPTION
ServiceNow InstanceThe ServiceNow instance that Service2CM will utilise for data retrieval. The instance URL must contain the trailing backslash /
Client IDThe Client Id of the OAuth Credential Connected App created in ServiceNow
Client SecretThe Client Secret value of the OAuth Credential Connected app created in ServiceNow
UsernameThe username of the administration account within Service Now that will be used to authenticate all data retrieval
PasswordThe password of the administration account within Service Now that will be used to authenticate all data retrieval
  1. On the Email Settings screen, enter the following fields

    image.png

    FIELDDESCRIPTION
    License ContactsContacts that will receive a notification when the 3652CM license is about to expire. Multiple email addresses can be added if separated with a ;
    From AddressThe email address that all email notifications are sent from
    Mail HostThe mail host that is used to send all email notifications from
    Mail PortThe mail port
  2. On the Custom Setup screen select the install location and click on the Next button

    image.png

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

    image.png  

  4. The installation will commence

    image.png

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

    image.png

CONFIGURATION​

IIS CONFIGURATION​

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

  2. From the Features View double click on Authentication button and ensure that only Windows Authentication is enabled

    image.png

    2022-12-02_12-11-59.png

  3. Right click the application in IIS and select theexplore 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 Service2CM 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 Always Running, Idle Time-out Action to Suspend and Idle Time-out Action (minutes) to 0

    image.png

  9. Click on the OK button

  10. Select the Service2CM 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

COMMAND LINE ARGUMENTS​

Functionality NameCommand Name
Domain for Application PoolWEB_APP_POOL_IDENTITY_DOMAIN
Username for Application PoolWEB_APP_POOL_IDENTITY_NAME
Password for Application Pool:WEB_APP_POOL_IDENTITY_PWD
Dataset IDDBID
Workgroup ServerWORKGROUP_SERVER
License PathLICENSE_PATH
Temp PathTEMP_PATH
ServiceNow InstanceINSTANCE
Client IDCLIENTID
Client SecretCLIENTSECRET
UsernameLOGINUSERNAME
PasswordLOGINPASSWORD
License ContactsLIC_CONTACTS
From AddressFROM_ADDRESS
Mail HostMAIL_HOST
Mail PortMAIL_PORT

CONTENT MANAGER CONFIGURATION​

The following additional fields are mandatory and need to be on the Service2CM Document Record Type that you will be using.

Note

All names of fields below are examples and can be set to your organisations desired terminology.

CONTENT MANAGER CONFIGURATION​

RECORD TYPE CONTAINMENT (OPTIONAL)​

If you wish to use Requests (REQ's) as the parent container for Request Items (RITM's) then the containment rules of your document record type will need to be adjusted.

Note

These changes only need to be made for the record type you are using for the connector.

  1. Right click your document record type and select Properties

  2. Click on the Containment Tab. In the dropdowns select Container must have a record type in the specific list for both sections

    2021-02-19_14-28-06.jpg

  3. Add your document record type to both lists

  4. Click OK

    2021-02-19_14-28-06.jpg

SERVICENOW REQUEST NUMBER ADDITIONAL FIELD​

To search for a Content Manager record based on the ServiceNow request number, an additional filed must be created to store the numeric identifier.

  1. Navigate to Content Manager Context, Search for ‘Additional Fields’ > All

  2. Right click in the view pane and click New Additional Field

    image.png

  3. Select String as Data Format

    image.png

  4. Name the Additional Field ServiceNow Request Number

    Note

    This must match the image below exactly

    additionalfield.jpg

  5. Click on the Next button

  6. The maximum length should be 255

  7. Click on the Next button and click on the Finish button

    field.jpg

    types.jpg

  8. Add the additional field to the document record type that will be used by the connector

CONTAINER ADDITIONAL FIELD​

To search for a unique container within Content Manager that stores Service Now requests, an additional field must be made to map between the two systems. This allows for a unique value from the request to be used to map to the correct container in Content Manager (Example: An employee number).

  1. Search for ‘Additional Fields’ > All

  2. Right click in the view pane and click New Additional Field

    image.png

  3. Select String as Data Format

    image.png

  4. Name the Additional Field ServiceNow Field

    2020-10-14_10-28-19.jpg

  5. Click on the Next button

  6. Set the Format as specified below. The maximum length should be 255.

    field.jpg

  7. Click on theNext button and click on the Finish button

Add the additional field to any container record types that are to be used with the connector.

SERVICE NOW CONFIGURATION​

TRANSFER STATE​

If Cases (CS) are intended for transferring from Service Now to Content Manager, a custom variable choice is required to indicate the success of the transfer into Content Manager. This will also assist with indicating when a case should be transferred within the workflow.

Note

This process must be completed by an Administrator within Service Now.

  1. The Transfer State is a choice list custom variable that must be active and on the form.

    2021-03-17_10-01-26.jpg

  2. The Transfer State must be in the following properties.

    2021-03-17_11-31-25.jpg 2021-03-17_11-32-38.jpg

  3. This property can be created using the Form Designer.

  4. Ensure that the Name is u_transfer_state, as Service2CM will look specifically for this name.

  5. Save this variable within the form.

UNINSTALLING FYB SERVICE2CM​

MANUAL UNINSTALL​

To uninstall the Service2CM manually please follow the steps below:

  1. Navigate to control panel

    controlpanel.jpg

  2. Click on the Uninstall a program option

    uninstall.jpg

  3. Locate FYB Service2CM in the list of Programs and feature

    uninstallprogram.jpg

  4. Right click on FYB Service2CM and click on the Uninstall button

    uninstallbutton.jpg

  5. If a warning Prompt appears, click on the Continue button

    warning.jpg

  6. Click the Yes button

    2021-01-22_9-25-25.jpg

  7. The uninstallation process will commence

    2021-01-22_9-25-38.jpg

  8. Open IIS once the uninstallation process is completed

  9. Locate Service2CM in IIS and right click > Remove

    remove.jpg

  10. When the prompt appears click on the Yes button

    areyousure.jpg