Build your Own Connector

The Connector Builder Page allows you to develop custom connectors so you can integrate other external applications seamlessly with ASM to pass and retrieve data.

Communication with the supported external applications is performed through connectors that you can now build in the Connector designer page in ASM, rather than wait for others to build and install them on your server.The Connector Builder page only supports building custom CMDB connectors for the time being.

Available in HERMES (ASM Version 10.6.5) and higher.

Configuring a connector in ASM requires some knowledge of API's. If you are not comfortable with this level of detail but wish to begin building your own connector, please reach out to your Technical Account Manager, or Alemba Support.

What problems does building a connector via the Connector Designer solve?

You can create a custom connector from scratch, build it exactly how you want it and get the information exactly how you need it!

You can now build a custom connector in ASM that will allow you to communicate with external applications to discover resources on those applications. Once detected, those resources can be imported into ASM as Federated CMDB records or lined to the existing CMDB records.

To create a custom connector, you must describe the API you want to connect to so that the connector you’re building understands the API’s operations and data structures.

In the Connector Builder page, you can determine the types of resources to be imported from the supported categories: Bulletin, CMDB Item, Contract, Cost Center, Knowledge, Location, Organization, Person and Subscriber Group.

What types of data are supported?

Depending on the 3rd party system and the type of data it provides, you can choose and specify which type of value a variable has.

What happens after you build the connector in the configuration process?

Once your connector has been built and tested, you can put your custom connector to work. You will need to configure the connector for ASM to successfully connect to the 3rd party source with the specified parameters.

1. Define a source to configure instances of external sources with which ASM can connect in order to import or update objects and exchange information. For integration with the Federated CMDB, a source is the system to which ASM can connect to import objects discovered by a network discovery tool into ASM or import users from a directory server.

2. Configure the resources that you defined in the Connector Builder. This enables you to view the resource type configured on a selected source and create mappings for each of these resource types. This will allow you to create mappings between the external resource and ASM CMDB item fields.

3. You can view and create schedules for running scans on sources for the purpose of importing external resources.

4. You can view the resource link types configured on a selected source and create mappings for each of these link types.

5. You can set up appropriate security rights for Analysts to manage external resources.

Build Your Own Connector, How-To

Building your connector is a multi-step process and it will be helpful to gather some information before-hand:

• Application ID

• Client Secret value (not the client secret ID)

• Determine the necessary security Roles for the type of connector you are building. For example, Intune requires DeviceManagementManaged, Devices.Read.All, and offline_access while Azure AD needs User.Read.All and Directory.Read.All

• Required URLs

• The Fields you wish to map (Create a Data Dictionary for future expansion or troubleshooting)

Getting Started

1. Access the Connector Builder: System Admin>Integration>Connector Builder

2. Click "Add Connector" to add a new connector

3. Enter the details

1. Configure Resource Settings, click the "+" to add a Resource

1. Click the "New Resource" Link to expand and enter the details

   

   
2. Complete the queries as follows:

All

Query: All

URL: [The Url to your end point]

Nested Objects: value

Paged? True

Starting Page No: 0

Page Size: Default is 100, increase as needed

Next Page Property: example [@odata.nextLink]

Search

Query: Search

URL: [The URL for the Search query to your endpoint]

Nested Objects: value

Paged? True

Starting Page No: 0

Page Size: Default is 100, increase as needed

Next Page Property: example [@odata.nextLink]

Retrieve

Query: Retrieve

URL: [The Url to your end point for the search results]

Nested Objects Paged? False

Page Size: Default is 100, increase as needed

Next Page Property: example [@odata.nextLink]

1. Complete the Resource Details

Resource examples

You will gather the resource details and add these to your data dictionary for the connector.

Resource Unique Identifier Field, example

Field ID: id

Data Type: String

Resource Display Field, example

Field ID: DeviceName

Data Type: String

Resource Last Modified Field, example

Field ID: lastsyncDateTime

Data Type: DateTime

1. Setup fields, Click the "New Fieldset" link.

The Fieldset defines the data set you want to use for this connector.

Fieldsets Details, example

Fieldset id: DeviceFields

Type: Relative

1. Add fields to the fieldset, Click the "+" to add a new Field

1. Click the "+" to repeat and add a new row for all fields you need to add to this fieldset

Link Settings

This section is not typically applicable to the configuration. If you need more information about Link Settings, please contact Alemba Support for assistance.

1. Save your new Connector

2. Configure your Source

   1. Navigate to System Admin>Integration>Sources

   2. Click the Add icon to add a new source
   3. Select the Connector you just defined, in this example we called it "Connector Builder Test", but yours will likely be some version of Microsoft_InTune, Asset Panda, Solar Winds, etc...

1. Complete the Source Properties.

Source Properties, example

URL: https://graph.microsoft.com

Test URL: v1.0/deviceManagement/managedDevices

Manage Token:

• Tokenname: Your Client Intune Token

• Grant Type: client_credentials

• Call back URL: https://yourclienturl.alembacloud.com/production/oauth2callback.htm

• Authorization URL: https://login.microsoftonline.com/{Azure Tenant ID}/oauth2/v2.0/authorize

• Access Token URL: https://login.microsoftonline.com/{Azure Tenant ID}/oauth2/v2.0/token

• Client ID: Value from the Azure App Registration

• Client Secret: The secret created for the App Registration

• Scope: https://graph.microsoft.com/.default

• State: Any secret value E.g. A complex password

1. Map Your Fields Under Resources

Please note that there are several fields that bring back data as bytes including Total and Free Storage space in Microsoft Intune and other Asset Discovery tools. If you wish to convert these to GB then you would need to use the transform function in ASM, for example: Math.Round(Convert.toDecimal(PhysicalMemoryinBytes)/1073741824,2)

1. Set up the integration's scheduled scan