ServiceChannel Integration

Prerequisites

The integration between ServiceChannel and Lucernex provides RE Real Estate information from Lucernex to facilities maintenance information in ServiceChannel so that critical information is available when maintenance activities are created, scheduled, or routed for work. This helps your organization align real estate and facilities management teams to increase efficiency in routing maintenance activities to correct stakeholders.

Information is sent from Lucernex to ServiceChannel once per day in the form of an Excel file with responsibility records belonging to Landlord. For example, HVAC = Landlord. ServiceChannel parses the file for deltas.

A Responsibility report runs daily if your organization uses this integration. This report gathers responsibility data and delivers it as a Excel file to an SFTP Secure File Transfer Protocol site that ServiceChannel automatically picks it up from. This automated process ensures consistent and timely delivery of essential data for maintenance management.

The SCLocationID on a Lucernex Contract, stores the ServiceChannel Location ID. You can use this to enter data manually or specify automatic inclusion of the data sent to ServiceChannel. This field is only visible when the integration is enabled.

You can use this field to manually input the ServiceChannellocation ID for contracts that already exist. The value of this field is sent to ServiceChannel with the responsibility data. The data is automatically included in new data sent to ServiceChannel.

Import contract data with SCLocationID field

The SCLocationID is included in the spreadsheet when you download the Contract Data Contract spreadsheet to use for a bulk import.

1. On the System Administration Dashboard in the Company Administration pane, click Import Data.

2. Select the Spreadsheets tab.

3. In Download Spreadsheet Templates, select Contract Data > Contract.

4. Click Download.

5. Edit the XLSX file that downloads.

6. Import the edited XLSX file.

Responsible Party Code

To map Responsibility Code pick list values in Lucernex with responsibility types in Service Channel, the values in Lucernex, must be assigned a parent value. You can now select a parent Responsible Party Value when you add or edit a Responsible Party Code.

1. On the System Administration Dashboard in the Company Administration pane, click Manage Firm Drop Downs.

2. Click Edit next to Responsibility Party Code.

3. Do one of the following:

   • Click Edit next to an existing code.

   • Click Add Responsible Party.

4. Enter or edit the fields on the leftmost side of the dialog.

5. Select the Responsibly Party Value you want as the parent value for this item.

6. Click Update.

You can also apply the parent value in bulk by exporting the existing Responsible Party Codes and then importing them.

1. On the System Administration Dashboard in the Company Administration pane, click Export Configuration.

2. On the Others tab, select Responsible Party.

3. Click Export Selected.

4. In the Data Export dialog that opens, click Save XML file.

5. Edit the XML file as required.

6. Import the edited XML file.

Service Channel Integration Report

The Service Channel Integration Report is a Global Report Template that provides key information about the integration activity between ServiceChannel and Lucernex including:

• Firm ID: Client

• Service Channel Location ID: Value of the Contract.ScLocationID field

• Category: Responsibility.CodeAssetCategoryID

• Responsibility Type: Responsibility.CodeResponsibilityTypeID

• Responsible Party: Parent Responsible Party Code

• Comments

• Responsibility RecID: ID of the responsibility record in Lucernex

• SubscriberID: Service Channel Subscriber ID

Create Service Channel Integration Report

To use the integration, you must create a Service Channel Integration Report with a Scheduled Job. To ensure the file name is one that is recognized by ServiceChannel, select Is Service Channel File Name? on the Scheduled Job associated with the report.

1. In Report Builder, click Create Report.

2. In A global Report, select Service Channel Integration Report.

3. Click Next.

4. Click Report Settings > Modify Report Details.

5. In Save Report for?, select Everyone in my company.

   If you do not select this option, the Schedule Job option is not displayed in the subsequent steps.

6. Click Save then click Close.

7. In the Saved Report List, click Edit in the row of the report you created.

8. Click Report Settings > Schedule Job.

   If Schedule Job does not display, this could be because the report is not saved for everyone in your company.

9. Click Add Scheduled Job.

10. Complete the fields in the Add Scheduled Job window that opens.

    • Name: Enter a name for the scheduled job using our Recommended Naming Conventions.

    • Time Out Report after # Minutes: Enter the number of minutes you want the report to time out after if the report is taking too long to generate.

    • Schedule Disabled (run Manually): Select to deactivate, but not delete the scheduled job. You can clear this check box if you want to reactivate the scheduled job in the future. You can select this check box if you want to configure a work flow step to run a scheduled job at the beginning or end of the step.

    • Skip items unchanged from last successful run: Improves performance by only processing changed items.

    • Limit entity in workflow steps: When a report is running from a workflow step, this limits the number of entities the system looks at to just the one related to the workflow step. This improves performance by only processing the entities necessary to generate the report.

      To use this option, you must add the Entity LxID field with search/runtime filter selected for Criteria / Conditions in each report where you want to limit the entity.

    • Schedule Job: Select the interval to run the report:

      • Hourly

      • Daily

      • Weekly

      • Monthly

    • Every: Enter the secondary interval criteria. The value of the Every changes depending upon the interval you select for Schedule Job. For example, if you select Monthly from the Schedule Job field, the Every changes to a field that you can use to select which day of the month you want the report to run.

    • Starting: Enter the starting date of the schedule.You can also click Calendar to open the Date Picker and select the appropriate date.

    • Run Scheduled Job As: Select the user whose security you want to use for the scheduled job.

      By default, scheduled jobs are run using the security settings of an Lx Administrator, so that all applicable data in your Lucernex firm is returned. You can run a scheduled job using the security and date settings of a specific user to get greater control over the data returned by your scheduled job. This user is required to accept the End-User License Agreement before the scheduled job can run.

11. Select Is Service Channel File Name?

    This ensures that the report is saved with a file name in a format that ServiceChannel is able to use such as FirmID_FirmName_SubscriberID_YYYYMMDD.xlsx.

12. Configure send Scheduled Job using SFTP

    For the Service Channel integration, a specific SFTP server is required. To obtain the necessary SFTP server details, contact your Professional Services representative and provide them with your company and project information to facilitate the process.

    1. Select FTP Report to.

       The SFTP fields become active, and the email fields deactivate.

       This option is selected by default.

    2. Select or clear the following check boxes:

       • Is Secure?: Select the check box if it is cleared.

       • PGP Encrypted?: Select if you want to use your public PGP Encryption key to encrypt the file prior to the file being sent to your SFTP server.

         You can enter your public PGP Encryption Key on the Admin > Manage Company > PGP page. If you want to use an alternative PGP encryption key for this scheduled job, select the alternate key from the menu to the right of the PGP Encrypted? check box. By default, this menu is set to Company Default PGP Key.

    3. Complete these fields:

       • Server: Enter the server address.

       • Path: Enter the path, beginning with / .

       • File: Enter the name of the file being created.

         Enter {TimeStamp} in the file name, exactly as formatted in this documentation, to append a time stamp to the file name. The use of {TimeStamp} in the file name is case specific, and must be typed exactly as shown. It is also critically important for troubleshooting so that historical files can be saved rather than overwriting each other.

       • Login Name: Enter the SFTP log in name to use with the specified server.

       • Password: Enter the SFTP password to use with the specified server.

       • Private Key (for SFTP): Enter the SFTP private key to use with the specified server in openssl format.

       We recommend you use either the SFTP Password or the Private Key field, but not both. If specified, the private key serves the same role as a password. There are many tools that can be used to create a SSL key pair, but IWMS can only accept openssl formatted private keys.

       For example, a popular open sourced Windows application named puttygen can be used to produce a SSL key pair, but the file format it produces is not openssl and will not work with IWMS unless you convert the puttygen format into openssl format. Fortunately, puttygen has a built in conversion utility that can be accessed via its Conversions > Export OpenSSH key menu item.

       The SFTP server must be configured to accept this private key as a form of authentication, so the key pair must be installed on the SFTP server.

    4. Enter the email address you want to send failure notices to if your scheduled job does not get processed in the Email Scheduled Job failure notice to field.

13. Click Add.

    The scheduled job is listed in the table.

14. Click Close.

15. To save your changes, click Save in the header of the Report Builder, to the right of the report name.