Configuring Connectors

Scheduling connectors within the LMS application requires the ALL_CONNECTOR role to be assigned to the administrator’s account of the consultant or partner who will be scheduling them. In addition, they must have the Edit permission contained in the ALL_CONNECTOR role.

The process itself consists of five steps:

1. Configure the Connectors Property File
2. Create the data input file
3. Upload data files
4. Scheduling
5. Data validation and troubleshooting

In our testing environment of the LMS, we need to configure the Connectors property file. This file contains common settings for all connectors as well as individual connector-specific settings.

To begin using connectors, you need to configure the Connectors property file.

1. In Learning Administration, navigate toSystem Administration → Configuration → System Configuration and select the Edit icon next to the CONNECTORS property file.
2. Copy the entire property file and save as a local text file.
   Note

   It is a best practice to copy and paste the file into your text editor, such as Notepad++ and edit the file in your editor. Save the unedited file first and version control.
3. Provide the system needed information as to where to find the uploaded data file(s) and where to generate an output report for download and email. Complete the necessary updates to enable connectors. Below is a sample of the updates needed.
   • FTP File Location: /FEED/UPLOAD/XX/
   • LMS Tenant Suffix Override: TRAINXX
   • Enable output report: connector.ftp.output.report.enable=true
   • FTP Reports to /FEED/DOWNLOAD/XX/
   • Email detail reports: true, you@yourcompany.com

   In the screenshot below, the sample edits are highlighted in yellow. You will need to place the file in the desired location by going into the SFTP location, to the FEED folder, to the UPLOAD folder, and then into your corresponding folder with your tenant ID.

   
4. Enter the SFTP login information so the system can get to the data files.
   Note

   This SFTP information will be provided to customers for their own instances. This is sample information (listed below).
   • SFTP port: connector.ftp.server=sftp8.sapsf.com
   • FTP User: kso-midmarket
   • FTP Password: krj09ufgdsf9ftg
   • Connector specific business rules and data mapping – Retrieve from the Connector Workbook.
   
5. After editing the property file in your text editor, copy paste the text back in your training instance and select Apply Changes to reflect the changes.
6. After you save, the password will be encrypted when you look at the CONNECTORS property file in the LMS.
7. If you want to enable input file archiving, navigate to System Administration → Connectors → Connector Settings, select the checkbox, enter the number of months, select Apply Changes.

When creating the input files that are needed to run the standard connectors, it is the customer's responsibility to create a process that will query their source system, to then produce a file and then place it in an SFTP location. Sometimes the data file can be an export from another system, but we can also manually create one.

Work with system managers to develop this export, and automate placement on the FTP location. It needs to be an ongoing query to then place that file in the SFTP location.

For all connector input files, the defaults of column delimiter is pipe with an end of row delimiter of !##! by default. It is possible to change these to other values, but care must be taken to ensure the type of value isn’t already in the customer’s data, which will cause issues when trying to import the file. Recommendation is to keep the default that is identified in the connector property file.

The naming convention for each data file must be followed exactly. For example, for the User Connector – SF, the filename will be user_data_train900.txt (where train900 is the customer tenant ID as specified in the CONNECTORS property file). It's important to remember that the Connector Workbook is very strict about this naming convention. If we deviate from it and use a different naming convention, the entire file will not be imported correctly.

For files created and exported from other systems, as well as manually created files, we will need to login to SFTP and navigate to the UPLOAD folder and create a new folder with the tenant ID. Once created, other systems may need to be configured to upload their export files to the correct folder, or the data files can be manually placed into the new folder.

1. Log into the SFTP server by navigating to the URL specified in the CONNECTORS property file and using the ID and login provided to the customer.

   For example, open up the URL for SFTP site in a browser: sftp8.sapsf.com and use the sample login information as seen in the figure below.

   
   Note

   The password will appear encrypted in the file so you will not be able to retrieve it from there.
2. Navigate to the FEED folder and then to the UPLOAD subfolder and add a new folder with the company’s tenant ID. For our example, we use TRAIN900.
3. In your new folder, use the Upload button to add your data files, such as the ones created for the administrators and Item connectors.
4. Double check that the files have the correct file names as specified in the Connectors Workbook.
   Note

   Once the data file is successfully uploaded to the FTP site and the scheduled connector process is executed, returning to the FTP Upload company folder will show that the uploaded file has been archived. If there are changes to the data file, the administrator must reload it to the FTP Upload company and schedule the connector file to run again.

Once the CONNECTORS property file has been properly configured, a sample input file created, and file placed in the desired location within the SFTP folder structure, the next step is to schedule the connectors. This will trigger the connector to retrieve the file from the SFTP location and import it into the LMS database.

1. Navigate to Learning Administration → System Administration → Connectors and find the specific connector you wish to schedule. In this example, we will schedule the Administrator Connector.
2. It is a best practice to test the FTP connection before scheduling a connector for the first time. Select the Test FTP Connection button. In a few moments, checkmarks should appear next to each test. If a test fails, you may need to troubleshoot and fix the issue.
3. Select the checkbox next to Schedule This Process and select Daily and a time of day. You can also enter an Email Address that will receive a log file whenever this connector runs.

   Typically, customers will schedule connectors to run at night, but for this example and since the connector is being tested for the first time, it is scheduled for a few minutes from the current time. Select Apply Changes and confirm that the Next Job Execution field shows the date and time entered.

4. Schedule the Item Connector the same way.

When testing the Connectors that have been scheduled, it is a best practice to examine the results to determine if any exceptions occurred. For the Administrator and Items connectors, it is important to make sure all entities were added as a result of the connectors.

To do this, you can confirm:

1. The connector job itself ran successfully at the time it was scheduled.
2. There are no errors. Select View Errors to review them.
3. The entities were successfully added from the file. Select View Results.

   From the list of results, select the View Details icon to see which records (if any) have been added. A report will generate to show you exactly how many records (entities) have been processed successfully.

   

   The Detailed Report will notify the administrator about the success or failure of the import. There are various potential reasons for the import failure, and the report will offer insights into those reasons. In the example above, you can clearly identify the import failed because a required field was left blank (null value) in the data import file on Line 3.

   Sometimes if there is a problem with how the file was named or the data fields not matching the header fields in the data file, the number of Processed Records will be zero and there might be a number in the Exceptions column.

   It is important to confirm that entities have been added correctly. For the Administrators, navigate to System Administration → Security and search for the two administrators. For the Items, navigate to Learning Activities → Items and search there. For the online item, you should be able to see the new content object from the Item’s Online Content tab.

   If only some of them were added or none at all were added, troubleshoot by checking the Upload and Download folders for the tenant (instance).

In addition to the steps necessary for the other connectors, the User Connector – SF (for employee data) will look for user data files that were placed into the SFTP folder as a result of the employee export. It is important that customers who have employee users in HCM configure both systems correctly so that the users from HCM are added to SAP SuccessFactors Learning.

Important fields to consider to include:

• NOTACTIVE – maps to STATUS and is a mandatory field
• STUD_ID - maps to USERID in HXM and is a mandatory field
• DMN_ID - critical for the security model in the LMS
• SUPER - maps to MANAGER in HXM
• ORG_ID – maps to DEPARTMENT
• REGION_ID - maps to DIVISION
• CNTRY – maps to COUNTRY (but connector will reject the user if the value for CNTRY does not already exist in the LMS)
• EMAIL_ADDR – maps to EMAIL
• HIRE-DTE – maps to HIREDATE but must be in a specific format: MON-DD-YYYY HH24:MI:SS

Schedule a recurring employee export job in Provisioning and be sure that the SFTP information is correct so that the export will add the user data file to the appropriate folder in FEED/UPLOAD (e.g. TRAIN900 or the company’s tenant ID).

Schedule the User Connector – SF to run regularly. This is typically set for an off peak time, usually on a nightly basis.

When testing this in the customer’s staging or test environment, verify that the users were added into SAP SuccessFactors Learning from HCM.