Tagged: ITSM

How to use the Cireson Asset Import Connector

A little while ago on the Cireson Community Forum a member asked for more details on how the Cireson Asset Import Connector works. So I decided to write a blog post about it to clear up exactly what the connector is and how it works. I also recorded a short video for those of you who do not like long winded blog posts. You can find the video here.

The Cireson Asset Import Connector is one of the solutions contained within the Cireson Asset Management Stream of products and allows for Asset Administrators to take the guesswork out of importing external data into System Center Service Manager. This app allows any out-of-the-box CMDB data, or any information in the Cireson Asset Management app, to be imported from external CSV, SQL, ODBC or LDAP sources of truth, exposing an intuitive interface that provides the ability to map columns and schedule imports when required.

All little know pub quiz fact is that the Cireson Asset Import App grew from the CSV import app which was the very first Cireson app to hit the market. Next time this question comes up in a pub quiz, rest easy knowing that you now have the answer and are in a pub that is so cool it asks question like that one! ūüôā

When you add the Cireson Asset Import app to a Service Manager environment, importing data becomes seamless. One-time imports and configuring XML files become a thing of the past. The straightforward app provides the organization with the ability to build an asset repository of information that is relevant and accurate when working with requests in Service Manager.

So lets get in to it… throughout the following post, I will call out important things to note and also what is generally regarded as “Best Practice” but always consider the¬†requirements and impact these settings may have.

1. Creating a new Asset Import Connector

  1. Within the SCSM console, select the Administration workspace.
  2. Right click the Connectors Node.
  3. Select Create Connector from the drop down menu.
  4. Select Asset Management Import Connector from the sub menu.
 ami01
 ami02 NOTE:

The sub menu option for Asset Management Import Connector (Import) is for creating pre-created or backed up Import Connectors.

Enter a name for the connector that will make sense to other administrators for future maintenance tasks.

Select a Management Pack (or create a new one) that will be used to contain the workflow information required for the workflow of the connector.

 ami03
 ami04 Cireson Best Practice:

Best practice for creation of Management Packs is to create these Management Packs via the SCSM authoring tool and giving it an internal and full name in the format of ‚Äú ‚Äď Asset management Import Connectors‚ÄĚ.

This then assists to identify the Management Pack when exported or backed up at a later date.

The next step will be different depending on the input data source. Select and use one of the following sections below before continuing.

2. Using a CSV Source

After completing the steps in the section below, browse to the location of the .CSV file that contains the asset data to import and select the Encoding Format of the file.

The selected path can be either a local path (on the SCSM workflow server) or a network share that has read permissions by the Workflow account.

The first line of the CSV file must contain the header row information for the data contained within.

 ami05
 ami04 Cireson Best Practice:

It is Cireson best practice to create a single folder that contains all the CSV import files for any connector that is being used. It is also best to configure the connectors to use a UNC path as the location path of the file selected as this allows the connector to be edited successfully from other computers.

 Continue the connector settings.

 3. Using a SQL Source

For Microsoft SQL Server data source:

Enter the SQL Connection string by clicking the ellipse button and entering the required connection information.

 ami02 NOTE:

If Windows Authentication is to be used, the SCSM Workflow account must have read access to the source database.

Enter the SQL query that will be used to extract the data required for this connector.

Click Execute Query to test the query and gather field name requirements for class property mapping.

The SQL Query Results field will show the number of row returned if the query was successful.

 ami06
Continue the connector settings.

4. Using a ODBC Source

For ODBC Server data source:

Create a File Data Source Name (DSN) that contains the Server, Database and username for the data source.

Browse the file system and select the File DSN.

 ami02 NOTE:

The SCSM Workflow account must have read access to the File DSN.

Enter the File DSN Password for the username within the File DSN.

Enter the SQL query that will be used to extract the data required for this connector.

Click Execute Query to test the query and gather field name requirements for class property mapping.

The SQL Query Results field will show the number of row returned if the query was successful.

 ami07ami08
Continue the connector settings.

 5. Using an LDAP Source

For an LDAP data source:

Enter the LDAP Server or Namespace and the LDAP Port (If required).

If the SCSM Workflow account does not have read access to the LDAP source, enter alternative credentials with the required rights.

Enter the LDAP Attributes that are required to be returned separated by commas.

Enter an LDAP search starting path to reduce the search scope as required.

Enter any LDAP Filter needed to refine the results to the specific required data.

Click Execute Query to test the query and gather field name requirements for class property mapping.

The LDAP Query Result field will show the number of row returned if the query was successful.

 ami09ami10
Continue the connector settings.

6. Connector Settings

Select the target class that the records will be imported in to. This might be one of the base classes (Such as Hardware Asset) or, if other relationships are required, selecting a combination class (Type Projection) that contains the relationships required for the import.

Enter a Workflow log path to track import results and reporting on success\failure.

 ami11
Set the required options for the instance of the Asset Import connector. See below for more details on these options.

Once all options are selected, click Next.

 ami12
Asset Import Connector Options:

Test Mode The connector will run and create log file for inspection without commiting any changes to the SCSM database.
This connector can create new items When enabled, this option will allow the connector to create new records within the database.

This is used to allow the import of new records.

This connector can update existing items When enabled, this option will allow the connector to update existing records that match the key fields the selected class.
This connector will DELETE ALL matching items only This option changes the behaviour from creation to deleting of records. Any record matched from the import data to an instance of the class will be removed from the SCSM database.

WARNING! If data is deleted it can not be recovered.

This connector will update multiple existing items matching specific custom keys
Do not replace \n with a linefeed By default, the improt connector will interperate any \n text as representing a new line and therefore will replcae it with a linefeed character within SQL.

7. Mapping Fields

Data Mappings allow the mapping of the specified input data to the properties of the selected target class within SCSM.

On the Data Mapping screen, if the option for ‚ÄúThis connector will update multiple existing items matching apecific custom keys‚ÄĚ is selected on the previous screen the first option that will show is for Custom Keys. Custom Keys are used to fins all existing matching items and update them as normal via the mappings below. At least one custom key is required.

The Custom Key can be any of the properties for the class that was selected for this connector.

Add the custom keys as required and map these to the data from the import source.

 ami13
 ami02 NOTE:

All Key Properties for the selected class as well as any Custom Keys are required fields and must be mapped to continue.

The property displayed in the left column will show all properties of the selected class, along with any extended properties that have been added for the class.

The Data Type in the middle column will show what input data type the property will expect. String (Key) identifies the primary key for the selected class.

The Mapped To value displayed in the right column will show drop-down values for each available column header from the specified source

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

Map all additional properties to the input data that is defined from the Input source.

Any properties that are mapped will be updated or entered as defined.

Any properties that are not mapped will not be updated.

 ami14
If a Combination Class is selected for the connector there will be additional mapping fields under the Relationship heading.

These can be used to map data from multiple classes together as relationships as required.

 ami15
Once all mappings are complete, click Next.

8. Connector Workflow Schedule

Some connectors will be run as a once off to import bulk data in to the SCSM database, whereas others might be run on a schedule to keep other data sources up-to-date within the database.

An example of a scheduled data source might be a connector in to a Mobile Device Management (MDM) solution or an accounting or purchase system (for invoices and Purchase Orders).

For connectors that will be only run once, select the option marked This connector will be run manually.

When using this option, a warning message will be displayed to remind administrators that the connector will only run when using the Synchronize Now task within the console.

For a reoccurring schedule, enter the frequency as either daily or as a regular reoccurrence with a set frequency.

Ensure the Connector Enabled option is enabled to all ow the connector to run. This option may help with the administration of the connector at a later date if it needs to be turned off for a period of time for maintenance or fault finding.

 ami16
When the scheduling information has been entered, click Create.  ami17

9. Manually Running a Connector

Once a connector has been created it will show within the Connectors node in the Administration workspace of the SCSM console. Within this node, administrators are able to see the current status of all connectors, when they were last started and finished and their percentage complete.

Administrators are also able to manually run a connector to either force the synchronization regardless of workflow schedule or to trigger a non-repeating connector.

To manually run a connector:

Within the SCSM console, select the Administration workspace.

Select the Connectors node.

 ami18
Select the Connector to be run and click the Synchronize Now task within the tasks pane.  ami19
If the connector does not have a schedule set (is disabled) then a message will appear informing that the connector is disabled and asking if it should still be run.

Click Yes to run the Synchronization.

 ami20
The connector workflow will then be scheduled to start at the next opportunity for the workflow engine.

10. Exporting and Importing a Connector

Once a connector has been configured the settings can be exported to allow administrators to copy the connector to a different environment (dev to prod).

To export and import a connector:

Within the environment to export from:

Within the SCSM console, select the Administration workspace.

Select the Connectors node.

 ami21
Select the Connector to be run and click the Export task within the tasks pane.

Save the connector XML file to a path and click Save.

 ami22
Within the environment to import in to:

On the Connectors node, select Create Connector from the drop down menu.

Select Asset Management Import Connector (Import) from the sub menu.

Browse to the folder containing the exported XML file, select the xml file to import and click OK.

 ami23
A window will appear to rename the Connector from its original name if required and change the Management Pack that holds the information.

If the connector is importing from a CSV file, an additional field will appear that is used to provide the source location of the CSV file required.

Enter the values needed and click OK.

 ami24
The connector will be imported and will now appear in the connectors node.

11. Deleting a Connector

If a connector is no longer needed, then it can be removed from the SCSM environment by deleting the connector from the console.

To delete a connector:

Within the environment to export from:

Within the SCSM console, select the Administration workspace.

Select the Connectors node.

 ami25
Click the Delete task from the tasks pane on the right of the screen.

Click OK on the message that appears to confirm the connector to be deleted.

The connector has previously imported data a second message will appear asking if the data that was imported from the connector should be deleted.

 ami26

Hope this gives you a clear idea of how this app comes together and works for your organization.

Leave a comment if you have any additional questions.

 

Advertisements

Getting More From ConfigMgr For SCSM

We all love Microsoft’s System Center Configuration Manager and the vast majority of the industry loves it too. As Microsoft have recently announced over 50Million end points are now covered by just the latest current branch build (1610) https://blogs.technet.microsoft.com/enterprisemobility/2016/11/18/configmgr-current-branch-surpasses-50m-managed-devices/?Ocid=C+E%20Social%20FY17_Social_TW_MSFTMobility_20161128_685262993

The amount of data points that are returned from the ConfigMgr client is huge and can be exceptionally useful when diagnosing issues or tracking down what is deployed in an organization.

However, out of the box, the data is limited to what Microsoft deem necessary. While this is fine for much of the time every now and then there is a requirement to find more or different information to track things that are not in the standard hardware inventory report.

A great example that was asked for recently is Monitors.

Some organizations want to be able to track monitors with their PC’s and therefore their locations etc.

What many people do not realise is that a monitors cable (even VGA) passes very basic information back to the PC. This data can contain a bunch of data that is relevant to the monitor such as:

  • Manufacturer
  • Model
  • Serial Number
  • Etc.

This data is an industry standard called Extended Display Identification Data (EDID). This data is in a consistent format so this allows us to be able to retrieve this data in a consistent way.

Once we retrieve the data we can use it to identify what Monitor is currently plugged in. All we then have to do is get the Configuration Manager client to return the data as part of the standard hardware inventory cycle.

Step 1: Storing the EDID Data Somewhere Locally

This step takes the EDID data and places it in to a location that we can simply retrieve via the ConfigMgr client.

To achieve this, we need to get the client to interrogate the monitor for the EDID information then save the data to an easy to retrieve location, such as the WMI of the local machine.

To do this, we use PowerShell.

Here is the code you will need:
Test this script before you use it in prod. The script is provided as is and is not supported. (The usual drill)

# Reads the 4 bytes following $index from $array then returns them as an integer interpreted in little endian
function Get-LittleEndianInt($array, $index) {

# Create a new temporary array to reverse the endianness in
$temp = @(0) * 4
[Array]::Copy($array, $index, $temp, 0, 4)
[Array]::Reverse($temp)

# Then convert the byte data to an integer
[System.BitConverter]::ToInt32($temp, 0)
}

# Creates a new class in WMI to store our data including fields for each of the data points that we can return
function Create-Wmi-Class() {
$newClass = New-Object System.Management.ManagementClass(“root\cimv2”, [String]::Empty, $null);
$newClass[“__CLASS”] = “MonitorDetails”;
$newClass.Qualifiers.Add(“Static”, $true)
$newClass.Properties.Add(“DeviceID”, [System.Management.CimType]::String, $false)
$newClass.Properties[“DeviceID”].Qualifiers.Add(“key”, $true)
$newClass.Properties[“DeviceID”].Qualifiers.Add(“read”, $true)
$newClass.Properties.Add(“ManufacturingYear”, [System.Management.CimType]::UInt32, $false)
$newClass.Properties[“ManufacturingYear”].Qualifiers.Add(“read”, $true)
$newClass.Properties.Add(“ManufacturingWeek”, [System.Management.CimType]::UInt32, $false)
$newClass.Properties[“ManufacturingWeek”].Qualifiers.Add(“read”, $true)
$newClass.Properties.Add(“DiagonalSize”, [System.Management.CimType]::UInt32, $false)
$newClass.Properties[“DiagonalSize”].Qualifiers.Add(“read”, $true)
$newClass.Properties[“DiagonalSize”].Qualifiers.Add(“Description”, “Diagonal size of the monitor in inches”)
$newClass.Properties.Add(“Manufacturer”, [System.Management.CimType]::String, $false)
$newClass.Properties[“Manufacturer”].Qualifiers.Add(“read”, $true)
$newClass.Properties.Add(“Name”, [System.Management.CimType]::String, $false)
$newClass.Properties[“Name”].Qualifiers.Add(“read”, $true)
$newClass.Properties.Add(“SerialNumber”, [System.Management.CimType]::String, $false)
$newClass.Properties[“SerialNumber”].Qualifiers.Add(“read”, $true)
$newClass.Put()
}

# Check whether we already created our custom WMI class on this PC, if not, create it
[void](Get-WmiObject MonitorDetails -ErrorAction SilentlyContinue -ErrorVariable wmiclasserror)

# If the wmiClassError is returned then assume that the WMI class does not exist yet and try to create a WMI class to hold the Monitor info
# If creating the WMI class fails, exit with error code 1
if ($wmiclasserror) {
try { Create-Wmi-Class }
catch {
“Could not create WMI class”
Exit 1
}
}

# Iterate through the monitors in Device Manager
$monitorInfo = @() #Empty array
Get-WmiObject Win32_PnPEntity -Filter “Service=’monitor'” | foreach-object { $k=0 } {
$mi = @{}
$mi.Caption = $_.Caption
$mi.DeviceID = $_.DeviceID

# Then look up its data in the registry
$path = “HKLM:\SYSTEM\CurrentControlSet\Enum\” + $_.DeviceID + “\Device Parameters”
$edid = (Get-ItemProperty $path EDID -ErrorAction SilentlyContinue).EDID

# Some monitors, especially those attached to VMs either don’t have a Device Parameters key or an EDID value. Skip these
if ($edid -ne $null) {

# Collect the information from the EDID array in a hashtable
$mi.Manufacturer += [char](64 + [Int32]($edid[8] / 4))
$mi.Manufacturer += [char](64 + [Int32]($edid[8] % 4) * 8 + [Int32]($edid[9] / 32))
$mi.Manufacturer += [char](64 + [Int32]($edid[9] % 32))
$mi.ManufacturingWeek = $edid[16]
$mi.ManufacturingYear = $edid[17] + 1990
$mi.HorizontalSize = $edid[21]
$mi.VerticalSize = $edid[22]
$mi.DiagonalSize = [Math]::Round([Math]::Sqrt($mi.HorizontalSize*$mi.HorizontalSize + $mi.VerticalSize*$mi.VerticalSize) / 2.54)

# Walk through the four descriptor fields
for ($i = 54; $i -lt 109; $i += 18) {

# Check if one of the descriptor fields is either the serial number or the monitor name
# If yes, extract the 13 bytes that contain the text and append them into a string
if ((Get-LittleEndianInt $edid $i) -eq 0xff) {
for ($j = $i+5; $edid[$j] -ne 10 -and $j -lt $i+18; $j++) { $mi.SerialNumber += [char]$edid[$j] }
}
if ((Get-LittleEndianInt $edid $i) -eq 0xfc) {
for ($j = $i+5; $edid[$j] -ne 10 -and $j -lt $i+18; $j++) { $mi.Name += [char]$edid[$j] }
}
}

# If the horizontal size of this monitor is zero, it’s a purely virtual one (i.e. RDP only) and shouldn’t be stored
if ($mi.HorizontalSize -ne 0) {
$monitorInfo += $mi
}
}
}

#$monitorInfo
# Clear WMI
Get-WmiObject MonitorDetails | Remove-WmiObject

# And store the data in WMI
$monitorInfo | % { $i=0 } {
[void](Set-WmiInstance -Path \\.\root\cimv2:MonitorDetails -Arguments @{DeviceID=$_.DeviceID; ManufacturingYear=$_.ManufacturingYear; `
ManufacturingWeek=$_.ManufacturingWeek; DiagonalSize=$_.DiagonalSize; Manufacturer=$_.Manufacturer; Name=$_.Name; SerialNumber=$_.SerialNumber})

#”Set-WmiInstance -Path \\.\root\cimv2:MonitorDetails -Arguments @{{DeviceID=`”{0}`”; ManufacturingYear={1}; ManufacturingWeek={2}; DiagonalSize={3}; Manufacturer=`”{4}`”; Name=`”{5}`”; SerialNumber=`”{6}`”}}” -f $_.DeviceID, $_.ManufacturingYear, $_.ManufacturingWeek, $_.DiagonalSize, $_.Manufacturer, $_.Name, $_.SerialNumber
$i++
}

The script needs to run on each PC on a regular interval to keep the data up-to-date. This ensures that if a monitor gets added or removed from a PC then the information is updated on a regular basis. Save the PowerShell script to a location that can be used by SCCM as the source location of a package. This location will be referenced as the Source Location for the remainder of this procedure.

Open the System Center 2012 Configuration Manager console  clip_image001
Select the Software Library workspace  clip_image002
Expand the Application Management node and select the Packages node  clip_image003
Select the subfolder where the package will be created, right click and select Create Package from the drop down list  clip_image004
Enter the following information:

Name: Monitor Details Gather

Description: Extract the monitor EDID information from the client and store the data in WMI ready for collection by SCCM

Version: 1.0

Click the checkbox labelled The package contains source files and click Browse

 clip_image005
Enter the UNC path to the Source Location folder created earlier in this procedure.

Click OK

Once back on the package screen, click Next

 clip_image006
Select Standard Program and click Next  clip_image007
Enter the following information:

Name: Get Monitor Details

Command Line: get-monitor-details.ps1

Run: Normal

Programs can run: Whether or not a user is logged on

Click Next

 clip_image008
Leave all settings as default and click Next  clip_image009

Confirm the settings and click Next to create the package

When the package creation is completed, click Close

Within the console, right click on the package and select Distribute Content from the drop down list  clip_imageb001
Click Next  clip_imageb002
Click Add and select Distribution Point from the drop down list  clip_imageb003
Select the distribution points that require the content and click OK  clip_imageb004
Once all distribution points have been added, click Next  clip_imageb005
Confirm all the settings and click Next  clip_imageb006
When the Distribute Content Wizard is completed, click Close  clip_imageb007

Once the package is created we need to deploy it out on to run on a regular schedule on clients. The script does need to be run often as the monitors will move from PC to PC over time. How frequently is up to each organization and what they are trying to achieve.

To setup a deployment:

Within the console, right click on the package and select Deploy from the drop down list  clip_imagec001
On the label collection label click the Browse button  clip_imagec002
Select the collection that the script will be deployed to and click OK.

On the previous screen, click Next

 clip_imagec003
Confirm that the content has been distributed to a distribution point and click Next  clip_imagec004
Select Required as the installation type and click Next  clip_imagec005
On the schedule wizard screen, click New  clip_imagec006
Click the Schedule button  clip_imagec007
Select the start time for when the script will run on the workstations.

Select a custom interval and set this schedule to recur every 1 days.

Click OK.

 clip_imagec008
Click OK  clip_imagec009
Click Next  clip_imagec010
Leave all settings as default and click Next  clip_imagec011
Leave all settings as default and click Next  clip_imagec012
Confirm the settings and click Next to create the package  clip_imagec013
When the Deploy software wizard is completed, click Close  clip_imagec014

Step 2: Retrieve the WMI Data via ConfigMgr

Now that we have the data stored in the WMI we need to get the ConfigMgr client to return the data next time it does a Hardware Inventory of the clients.

To ensure it is possible to read the correct fields within ConfigMgr the WMI class needs to exist on at least one PC that you have access to.

Select a PC to run the script on and execute the PS1 file.

This PC will be used later to query the class that will allow System Center 2012 Configuration Manager to collect inventory from all other workstations.

Select the Administration workspace  clip_imaged001
Select the Client Settings node  clip_imaged002
Select the Default Client Settings item,
OR
a client settings item that affects all workstation clientsRight click and select Properties
 clip_imaged003
Select Hardware Inventory from the settings list  clip_imaged004
Click Set Classes  clip_imaged005
Click Add  clip_imaged006
Click Connect  clip_imaged007
Enter the Computer name that the script was run on earlier in this procedure and click Connect  clip_imaged008
Select the MonitorDetails class from the list and click OK.

If the MonitorDetails class is not there, then the script has not run successfully on the computer you are connecting to. Make sure you test the PowerShell script and repeat if necessary.

Once the class is selected, click OK on the remaining open windows

 clip_imaged009

This process tells the client to retrieve the WMI class that we just created an populated using our PowerShell script. Once this is set, it will not need to be revisited unless the client settings change or are recreated for any reason.

And there we have it.

The PowerShell script will go out and run against clients updating the WMI and as these clients report in their Hardware inventory the monitor details will appear in the resource explorer like any other hardware detail.

For many, this may enough as they will be able to report on the ConfigMgr database and get the results they are after. Others want a more thorough view of Asset Management and may want to pull this information in to their Asset management solution to show these relationships.

In my next blog post, I will go through how to use the Cireson Asset Management Solution to pull in this data, create or update a Hardware Asset item for each monitor and finally how to associate it with the computer it is plugged in to.