How to Use the Asset Import Connectors Create a New Import Connector General Details Data Mappings Workflow Schedule Obtain source data from Microsoft SQL Obtain source data using ODBC File DNS Obtain source data using LDAP Query Export a Connector Import a Connector Update an Import Connector Delete an Import Connector Import a 1-Many Relationship Purpose: This guide will explain how to create, update, and delete an Asset Import Connector. It will also include tips, best practices, gotchas, and other information to make using the connector as easy as possible. If you do not understand a step or feel some more explanation would help you better, please let us know. Prerequisite: Download and populate the Asset Import Master Spreadsheet in the Asset Management User Guides on the Cireson Portal.
Create a New Import Connector Following the installation, licensing, and configuration of the Asset Import app, SCSM Administrators will now see a new connector type within the Administration > Connectors area. 1. Navigate to Administration > Connectors 2. Within the Tasks menu, select Create Connector > Asset Management Import Connector www.cireson.com 2 of 28 http://kb.cireson.com
General Details Select/populate the following fields within the connector to import data for any Configuration Item class available in SCSM. 3. Connector Name Enter a name for the connector This name can be changed later if needed, and is used partly to name the workflow log file 4. Management Pack If creating your first Import Connector, Select the New button Create a new Management Pack called Company Name Asset Management Import Connectors Do not use this MP to hold anything else except for Import Connectors www.cireson.com 3 of 28 http://kb.cireson.com
Do not select any of the out-of-the box management packs 5. Source CSV format file with header row Browse to the location of the.csv file This path can be a local path (on the Workflow Server) or network share, accessible by the Workflow Account. It is recommended to enter a UNC Path here. It is a good idea to create a folder to store all CSV files in The first line in the CSV file must be a header row containing column names 6. Obtain source data from Microsoft SQL Server For SQL sources, see SQL Connections at the end of this document 7. Obtain source data using an ODBC File DSN For ODBC File DSN source, see ODBC Connections at the end of this document 8. Obtain source data using an LDAP query For LDAP query source, see LDAP Connections at the end of this document 9. Target Class Choose the Configuration Item based class that you would like to import data into These are your possible selections for Asset Management use: - Catalog Item (Cireson Asset Management) - Consumable (Cireson Asset Management) - Cost Center (Cireson Asset Management) - Hardware Asset (Cireson Asset Management) - Invoice (Cireson Asset Management) - Lease (Cireson Asset Management) - License (Cireson Asset Management) - Location (Cireson Asset Management) - Organization (Cireson Asset Management) - Purchase (Cireson Asset Management) - Purchase Order (Cireson Asset Management) - Software Asset (Cireson Asset Management) - Standard (Cireson Asset Management) - Subnet (Cireson Asset Management) - Support Contract (Cireson Asset Management) - Vendor (Cireson Asset Management) - Warranty (Cireson Asset Management) www.cireson.com 4 of 28 http://kb.cireson.com
10. If you wish to use/map relationships, select a Combination Class Based on the selected Target Class from (step 7), you will be presented with different options based on that classes possible relationships. Choose the option that contains the relationships you wish to map. You may want to select one and select Next and scroll to the bottom of the page to see what relationships the different choices display. You can always select Previous to return to this page. For large import processes, the workflow processing speed can be improved slightly by selecting a Combination Class that most closely contains the relationships that you want to map. Do not select a combination class unless you want to import relationship data. To display all the relationships for a Target Class, select the option with (Full) in the name, as shown above. You can start typing the combination class name instead of selecting the dropdown arrow 11. Workflow log folder path If you have identified this path in the Asset Import Settings, it will be auto populated If you have not set this in the settings, you will have to enter this path on every connector. Just enter it in the settings to save time and make your life easier. This path should be a UNC path to a shared folder, otherwise it will only work when logged in locally to the server. This will ensure all admins can create/run connectors from their computers. It is a good idea to create a folder to store all import logs files. Create a shortcut to this folder on your desktop, as you will be accessing these logs frequently during the import process. 12. Test mode Please always check this when creating a connector. You will be able to review the log as if the data was being imported, without any data being written to the database. After you review the log and decide everything is ok, you can open the connector, uncheck, and select Sync Now to import the data. If you have not set this in the settings, you will have to check this box on every connector. Just enter it in the settings to save time and make your life easier. Check the How to Read an Asset Import Log File for more details on what error or warnings you might receive, and how to fix them. 13. Select Next www.cireson.com 5 of 28 http://kb.cireson.com
Example of Asset Management Import Connector General Details Settings: www.cireson.com 6 of 28 http://kb.cireson.com
Data Mappings Data Mappings allow for you to map the specified CSV, ODBC, SQL, or LDAP data to the properties of the selected target class within SCSM. For this example, we will be referencing the column names provided in the Asset Import Master Spreadsheet located in the Asset Management User Guide on the Cireson Portal. It is highly suggested to use this spreadsheet to normalize your asset data into, and create the.csv files from. More details about this spreadsheet are provided below the link for the download. The data mapping section consists of 3 parts: Keys and required properties Optional properties Relationships 13. Keys and required properties You must map all keys and required properties, including Display Name. Even though the Display Name is not a key or required property, not setting it can cause issues, therefore the Asset Import app requires it to be set also. Property The Property displayed here in the left column will also be shown on the Asset Import Master Spreadsheet as the 1 st Row. This column will show all properties of this class, along with any extended properties you have added for this class. Data Type The Data Type displayed here in the middle column will also be shown on the Asset Import Master Spreadsheet as the 3 rd Row. This reference shows what input data type the property will expect. String (Key) identifies the primary key for this class. The corresponding Mapped To selection is used to find existing instances of the specified class to update. If no instance is found, a new instance will be created. Mapped To The Mapped To value displayed here in the right column will also be shown on the CSV File Creator spreadsheet as the 4 th row. The drop-down values for each property contains available column headers from the specified source CSV file header row, or the SQL Query column names. If you are using the provided spreadsheet, most property names will matchup exactly or very closely with the Mapped To name. The Hardware Asset ID should be mapped to the primary key selection you chose in the Asset Management Settings. (Serial Number, Asset Tag, GUID, etc.) It is recommended to use Serial Number as the primary key When creating connectors for all other classes except hardware, the Mapped To selection for these first two required fields can be the same. There will be two columns in the spreadsheet, but the Display Name column does not need to be filled in. A few Examples below: www.cireson.com 7 of 28 http://kb.cireson.com
14. Optional Properties As stated, these Mapped To fields do not have to be entered. If you have used the provided spreadsheet to create your.csv file, it is a matter of simply matching the Mapped To name in the drop-down box, to the Property. You only have to map the properties you are going to import at that time. To delete a value in the Mapped To field, select the field and press the Delete key Two properties you will NEVER map a value to are the Asset Status and Object Status. These are internal SCSM properties that are not used in Cireson Asset Management. www.cireson.com 8 of 28 http://kb.cireson.com
15. Relationships Relationship Mappings If you selected a combination class on the previous page, you may also configure Relationship Mappings. In the above image, the Cost Center Has Organization relationship only has one valid target class, Organization, and this class only has one key. We know this because Target Class\Key\Data Type is a text box for this relationship. The relationship has been mapped to Organization Name. The relationship Owned By User has multiple possible target classes, or one possible target class with more than one key (which is the case in this example). We know this because this time, Target Class\Key\Data Type is a drop-down list containing available target classes. In the image above, Domain User or Group has been selected. This added beneath it Domain User or Group\Domain\string and Domain User or Group\User Name\string, which are the keys for Domain User or Group. These are mapped to Owned By Domain and Owned By Username. If you have selected the checkbox in the Asset Import settings to process to-many relationships: You will see extra relationships in this section. Details on how to map these properties are in the Importing a 1-to-Many Relationship section at the end of this document. www.cireson.com 9 of 28 http://kb.cireson.com
Example of Asset Management Import Connector Data Mappings Settings for Cost Center: Properties to Not Map for Each Class There are certain properties you will never choose a Mapped To value for, due to how that value is used in the Asset Management application. The field may not appear on the actual form, or the field may be populated based on a calculation. Below will be a list of the classes, followed by the property you should not ever map anything to. If you are using the provided Asset Import Master Spreadsheet, all the properties listed can be mapped to. The fields that should not be mapped to were left out. Hardware Asset Notes Lease\Support Contract\Warranty Contract Status License License Status www.cireson.com 10 of 28 http://kb.cireson.com
Workflow Schedule Option 1: Manual Import If you are doing an initial import of your asset data, or importing bulk assets manually, check this When you do, you will get the following pop-up, the schedule section below the checkbox will be greyed out, and the connector will remain disabled. Do NOT enable a connector that has this checkbox checked. Select OK, then Select Create in the bottom right corner of the window When the Connector has been created successfully, you will see the following pop-up window If an error appears, please follow what it states to correct the issue. There are no known errors that would occur, so if you receive one, please screenshot and send to send to us from the Cireson Portal. Select Close To run the connector, look for your connector that has not been run and select it To Sync and Run the connector manually, select Synchronize Now in the task list on the right You will receive a pop-up window, asking you if you want to run this manually, and informing you that the connector is disabled and therefore has no automated scheduled set. Select Yes www.cireson.com 11 of 28 http://kb.cireson.com
You will receive this pop-up to inform you that it will take a few minutes to run. Select OK At this point, you can open the folder you chose to save the Asset Import Log files in and watch the data import into the file. To see more about how to read the log files review the User Guide for Reading Log Files in the Asset Import User Guide on the Cireson Portal. After you have verified there are no errors and understand the warnings in the log, open the connector, uncheck the Test Mode checkbox, select OK, and re-sync the connector to import data Option 2: Scheduled Import This option can be used if there is going to be a CSV file populate from the output of a different information system, or Analysts are going to enter asset data into a spreadsheet that you want to import on a frequent basis. There are two options at this time: Daily or Other/Frequency. Typically a daily import is sufficient enough. www.cireson.com 12 of 28 http://kb.cireson.com
Daily You may enter a Start Time in the following formats: 02:00 am, 01:30 pm, 14:00, 10:00 If am or pm are omitted, the time is assumed to be in 24 hour format. When a connector is edited, the time is always returned in 24 hour format as this is how it is stored in the workflow configuration. Select which days you would like the workflow to run on: One or more of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday or Saturday Other Enter a value for Frequency Select Hours or Minutes Check Connector Enabled After you have setup the Daily or Frequency schedule, select Create From here, you can follow the same procedure noted above for Option 1: Manual Import Note: If you set the frequency too close together, you will cause the workflows to freeze up www.cireson.com 13 of 28 http://kb.cireson.com
Example of Asset Management Import Connector Workflow Schedule: www.cireson.com 14 of 28 http://kb.cireson.com
SQL Connections 1. To use Microsoft SQL Server as a data source instead of a CSV file, select Obtain source data from Microsoft SQL Server. 2. Select to configure a SQL Connection String 3. Enter the SQL Server (or use SERVER\INSTANCE format to use a named instance) 4. Enter the database name 5. If SQL Server Authentication is used instead of Windows Authentication, Enter the SQL credentials 6. If Windows Authentication is used, the Workflow Account must have read access to the configured database. 7. Select Test to enable the OK button if the connection was successful, Select OK www.cireson.com 15 of 28 http://kb.cireson.com
Example of the SQL Connections Configuration: Note: If Windows Authentication is used, this test is performed using the current user credentials and not those of the Workflow Account. In this case, the test simply confirms that the server and database are valid and can be connected to. Later, if the Workflow Account cannot connect, an error will be logged in the log file and the connector will show an error status. If the current user has no rights to the database, and these cannot be granted, SQL authentication must be used. Click OK to use the tested connection string. Enter a SQL Query that will return at least one row, then click Execute Query to continue. www.cireson.com 16 of 28 http://kb.cireson.com
ODBC File DSN Connections 1. To use an ODBC File DSN as a data source instead of a CSV file, select Obtain source data using an ODBC File DNS. 2. Select to navigate to the file 3. Enter the File DSN Password 4. Enter a SQL Query that will return at least one row, then Select Execute Query to continue. www.cireson.com 17 of 28 http://kb.cireson.com
LDAP Connections 1. To use an LDAP Query as a data source instead of a CSV file, select Obtain source data using an LDPA query. 2. Enter the LDAP Server or Namespace 3. Optionally, Enter the LDAP Port 4. If the login account you are using does not have permissions, Enter Username, Password, & Domain 5. Enter the LDAP Attributes 6. Enter the LDAP search starting path 7. Enter the LDAP Filter 8. Select Execute Query www.cireson.com 18 of 28 http://kb.cireson.com
www.cireson.com 19 of 28 http://kb.cireson.com
Export a Connector If you have configured a connector and want to copy it over to a different environment (dev to prod) or you just want to copy a connector for your current environment, you can use the steps below to accomplish this. 1. Navigate to Administration > Connectors 2. Select the Connector you want to export, and Select the Export Task 3. Enter the Path and File Name, and Select Save www.cireson.com 20 of 28 http://kb.cireson.com
Import a Connector Once you have exported a connector, you are ready to import it into your same environment (basically copy), or import it into a different environment. 1. Navigate to Administration > Connectors 2. Select Create Connector, then Asset Management Import Connector (Import) 3. Select the connector you want to import, and Select Open 4. Verify or Change the Connector Name 5. Verify or Change the Management Pack 6. Choose the.csv file, this should have just been copied over to your new location. Do not change the name if you don t have to. Otherwise, you will have to redo the mapping section of the connector. 7. You can now select Synchronize Now or allow the Scheduled Import to begin www.cireson.com 21 of 28 http://kb.cireson.com
Update an Import Connector Note: Place the all CSV Files you want to import into a folder and do not move them. If you move the CSV file or rename it, you will see the following when opening the connector You will see a * next to General Settings, Data Mappings, and Source CSV form, and the Data Mappings section will be blank You will have to either browse to the CSV file and remap the properties, or place the csv file in the source path it is looking for with the same file name The following items will show what can and cannot be modified on a connector that has already been created Can be modified Connector Name Data Mappings Workflow Schedule Cannot be modified Management Pack Source CSV can be changed, but you will be required to remap all the properties www.cireson.com 22 of 28 http://kb.cireson.com
Delete an Import Connector Decision: Do you want to remove the data the connector imported, or do you want to keep the data? 1. Select the connector you wish to delete in the Administration > Connectors view 2. Select the Delete task on the right 3. The following window will appear. If you select No, you will cancel the request to delete the connector. If you select Yes, you will see this window. 4. If you select Yes, the data that was imported with this connector will be removed from Service Manager. If you select No, you will delete the connector, but all data will remain in Service Manager. www.cireson.com 23 of 28 http://kb.cireson.com
Import a 1-to-Many Relationship In the Asset Import Master Spreadsheet and other asset import documents, you will see class relationships that are shown in green text. This is to show the 1-to-Many relationships that are available for import into the Asset Management App. They will often have a (MR) placed before or after the relationship. All Available 1-to-Many Relationships by Class: Catalog Item Consumable Cost Center Invoice License Location Organization Purchase Order Assigned Assets Assigned Users Cost Center Warranty Lease Support Contract Assigned Computers Assigned Users Subnet Organization Has Locations Purchase Order Invoice Warranty Lease Support Contract www.cireson.com 24 of 28 http://kb.cireson.com
Purchase Standard Vendor Lease Support Contract Warranty Hardware Asset Software Asset License Warranty Lease Support Contract Configuration Item Superseded Lease Superseded Support Contract Superseded Warranty Hardware Asset Purchase Related Computer Related Software Item Authorized Computer Authorized User License Purchase Authorized Locations Authorized Organizations Authorized Cost Centers Assigned Users www.cireson.com 25 of 28 http://kb.cireson.com
Assigned Computers Upgrade Licenses Downgrade Licenses To see the additional 1-to-Many relationships in the import connector relationship section, you must check the following checkbox in the Cireson Asset Management Import Settings : The mapping process is a bit different than the 1-to-1 relationships. When you select the drop-down for the Target Class/Key/Data Type and select an option, you may see the following. The text that is displayed under the drop-down will tell you what format the csv file must follow. Instead of entering data into the.csv file, you will be entering a path to a file, which is formatted according to the relationship you selected. www.cireson.com 26 of 28 http://kb.cireson.com
Steps to Map 1-to-Many Relationships For this example, we will use importing the Authorized Users for a Software Asset 1. Share out the folder that will store your.csv files to the Workflow Account 2. Create a.csv file named after the class and property you are going to import. (Examples Below) Software Asset Has Authorized User.csv Hardware Asset.csv Location Subnet.csv The csv file must match the format that is displayed below the drop-down selection for each property. Do not enter headers for this.csv file. 3. Place the path and filename in the appropriate column in the master.csv file spreadsheet along with any additional information you wish to import. At minimum, you will need the primary key(s) mapped. General Examples: Software Authorized User Example: 4. Save the Software Asset Tab as a.csv file. Ensure you remove the unneeded rows and columns first. Details are on the Notes tab. 5. Create a Connector, or modify a Connector to map the appropriate relationship www.cireson.com 27 of 28 http://kb.cireson.com
6. Synchronize the Connector in Test Mode 7. Review the Import Log, then remove Test Mode and Re-sync connector www.cireson.com 28 of 28 http://kb.cireson.com