How to Build Your Own Connector

The Connector Builder Page allows you to develop custom connectors so you can integrate other external applications seamlessly with ASM using the REST API.

Communication with 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.

Capability effective as of: Alemba Service Manager HERMES v10.6.1.

The Connector Builder page only supports building custom Federated CMDB connectors for the following:

• Person

• Bulletin

• CMDB Item

• Contract

• Cost Center

• Location

• Organization

• Person

• Subscriber Group

Accessing the Connector

1. Go to Menu>System Administration>Integration

2. Select Connector Builder

3. To add a new connector, press Add Connector

4. To view an existing connector, double-click

The Connector Builder Page

This page can be used to create new connectors and manage integrations with REST API’s. This screen allows you to build connectors.

1. To build a new connector, press Add Connector and a New Connector Builder Page loads.

2. Complete all the relevant fields: Name, Authentication, Resource Settings, Resource Details, Queries, Unique Identifier, etc...

Authentication

For authentication, you have 2 choices:

• Basic: the simplest type of authentication, where the user will have to provide a valid username and password before using the API.

• OAuth: uses the OAuth open-standard authentication framework to authenticate with the service, providing mechanisms for user authentication. OAuth does not share password data but instead uses authorisation tokens to prove an identity between users and service providers. OAuth is an authentication protocol that allows you to approve one application interacting with another on your behalf without giving away the password.

Resource Settings

By clicking on the plus symbol, a new section is created “New Resource” on which you can delete or expand either by clicking on the expand button or clicking on the entire section.

This new section allows you to create and define the resources and multiple new resources can be added.

The resources created in the Connector Builder will be displayed in the Integration Resources Page.

The following groups of fields are presented in the screen:

• Resource Details

• Queries

• Resource Unique Identifier Field

• Resource Display Field

• Resource Last Modified Field

• Field sets

Help icons are displayed near each field to give additional information and useful examples.

Resource Details

In this section, you will create and define the resource that you want to build.

1. Resource Display Name *: This is the value that will be seen when mapping a resource.

2. Resource Id *: A unique value for the resource to be used in ASM.

3. Resource Category*: This will determine the type of resource to be imported. Select from the list of available resource types:

   • Person

   • Bulletin

   • CMDB Item

   • Contract

   • Cost Center

   • Location

   • Organisation

   • Person

   • Subscriber Group

4. Resource Description *: A description of the resource.

Resource Unique Identifier Field

The Field ID value needs to be the JSON attribute of the resource unique ID.

1. Field ID*: unique identifier of what gets returned

2. Data Type*: specifies which type of value a variable has and what type of mathematical, relational, or logical operation can be applied and chosen from the from the dropdown list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

Data Type	Used for	Example
Blob	Stores binary data as a single entity	Images, Audio, Multimedia objects, etc
Boolean	Representing logical values	TRUE, FALSE
DateTime	Stores an instant in time expressed as a calendar date and time of the day	YYYY-MM-DDThh:mm:ss, etc
Float (Real)	Numeric variable which includes all the integer numbers plus their fractions or decimals	3.15, 9.06, 00.13
GUID	Text string that represents and identification (Globally unique identifier)	ID software, hardware, documents, etc.
Integer	Numeric variable without a decimal-whole numbers	7,12, 999
Long	Used when you need a range of values more than those provided by Integer
Password	Represents a password value
String	Holds a list of characters of any length. Therefore, it can represent alphanumeric data and symbols	Hello world, Alice, Bob123

Resource Display Field

The Field ID value needs to be the JSON attribute of the resource display name.

Field ID*: Unique identifier of what gets returned

Data Type*: Specifies which type of value a variable has and what type of mathematical, relational, or logical operation can be appliedà dropdown button to choose from the list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

Resource Last Modified Field

Field ID*: Unique identifier of what gets returned

Data Type*: Specifies which type of value a variable has and what type of mathematical, relational, or logical operation can be appliedà dropdown button to choose from the list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

Field Sets

A field set is a definition of how a particular set of readable data should be retrieved and represented as a list of fields.

Multiple field sets can be combined and used to present a consolidated set of data, however field IDs must be unique with the resulting schema or field lists, so conflicts in field ID result in data being over-written.

If you have multiple field sets for the same resource and/or you’re using mapped field sets that use a separate query, it will impact the performance of the connector. This is due to the fact that it’s going to run multiple requests to the API for every resource it detects.

Field sets are groups of data that you can retrieve using a particular API call. By using this option, you can customise what kind of data should be retrieved from the 3rd party system and returned to ASM.

Most of the time, by just retrieving an entity, will have all the information that you need. For example, just retrieving a configuration item or person, will have all the information that you need, there’s no need to make another API call and combine field sets to bring more information.

Add a new Field Set

By clicking on the Add button, a new section is created “new_field_set*” on which you can delete or expand either by clicking on the expand button or clicking on the entire section.

This new section allows you to create the field sets and multiple new field sets can be added.

1. Fieldset ID*: Unique identifier of what gets returned

2. Type: dropdown button to choose from the list: Relative, Mapped.

   • Relative: will use the results from the Queries so every field that is added to the field set needs to get returned in all 3 queries.

   • Mapped: will run a separate query to bring back the fields -> Linked Query

3. Field set Query: This query will be used when retrieving fieldset data.

4. The URL * field: the API reference will be provided by the 3rd party system.

5. The Nested Object field: add a value here if you would like to select a nested object in the response.

Example: You would enter results if you would like to select the results array from a search query response: { "results": [ { "Key": "Test", "Value": true } ], "_self": "api:v2/test" }

6. The Paged? Checkbox: Enable this option if you would like to page the results. This may improve performance. If paging is enabled, the following parameters are required int the URL:

Example: api/v2/configuration-item/@UNIQUEID

• Starting Page No*: This value will be used in the query as the page, offset or skip query parameters.

• Page Size*: This value will be used in the query as the limit or top of the query parameters.

• Skip Records? Checkbox: Enable this option if the API skips/offsets records, rather than incrementing page numbers.

• @UNIQUEID: This parameter is required and will be the unique id of source.

Link Settings

Once the Resources are defined, you should be able to link them if the API supports this action.

Not all APIs will support linking.

1. Click the Add button.

2. A new section is created “New Link*” on which you can delete or expandeither by clicking on the expand button or clicking on the entire section.
3. Complete the link settings. Help icons are displayed near each item to give you further instruction. The following group of fields are presented in the screen:

4. Link Details

   • Link Display Name* is the vaue that will be seen when mapping a resource link.

   • Link ID* is a unique value for the link to be used in ASM

   • Link Description* is the ASM detailed description of the link.

5. Resource A Unique Identifier Field - dropdown button (Combo box) to select from resources. The field ID value needs to be the JSON attribute of the resource A’s unique ID.

   • Field ID*: Unique identifier

   • Data type* is the dropdown button to choose from the list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

6. Resource B Unique Identifier Field - dropdown button (Combo box) to select from resources. The field ID value needs to be the JSON attribute of the resource B’s unique ID.

   • Field ID*: Unique identifier

   • Data type* is the dropdown button to choose from the list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

7. Link Sync Type* - Select the sync type that will determine what type of query will be run when detecting links.

   • Absolute: Specifies that links should not be synchronized relative to a resource. The query used will need to return both resource A and resource B unique Id's.

   • Relative To A: Specifies that links will be synchronized relative to resource A. The @RESOURCEAID parameter will be passed to the query.

   • Relative To B: Specifies that links will be synchronized relative to resource B. The @RESOURCEBID parameter will be passed to the query.

8. Link Query - This query will be used when detecting links between two resources.

   • The URL * field: the API reference will be provided by the 3rd party system.

   • The Nested Object field: add a value here if you would like to select a nested object in the response.

Example: You would enter results if you would like to select the results array from a search query response: { "results": [ { "Key": "Test", "Value": true } ], "_self": "api:v2/test" }

9. The Paged? Checkbox: Enable this option if you would like to page the results. This may improve performance.

• Starting Page No*: This value will be used in the query as the page, offset or skip query parameters.

• Page Size*: This value will be used in the query as the limit or top of the query parameters.

• Skip Records? Checkbox: Enable this option if the API skips/offsets records, rather than incrementing page numbers.

• Optional Parameters:

  • @RESOURCEAID: Use this parameter only when Relative to A sync type is selected. This parameter will be replaced with Resource A's unique id

  • @RESOURCEBID: Use this parameter only when Relative to B sync type is selected. This parameter will be replaced with Resource B's unique id

  • If paging is enabled the following parameters are required in the URL:

    • @PAGESIZE: Indicates the page size. To be used with limit or top query parameters.

    • @PAGENO: Indicates the paging position. To be used with page, offset or skip query parameters.

Example: api/v2/configuration-item/@RESOURCEAID/links

Queries

With the CMDB connectors there are 3 main queries: Query All, Query Search and Query Retrieve.

The URL fields need to be populated with 3 distinct types of API calls. The host's name is not included at this stage. The API references will be provided in the 3rd party system documentation.

Retrieving lots of data from the API could possibly impact the connector’s performance. Best practice is to select individual fields/properties in the request queries whenever possible. It is recommended to do that especially with the Query All and Query Search where the case is that lots of objects could be potentially returned.

Query All

This query will be used to return all the resources in the given scope. Runs a federated scan and retrieves all the resources from the 3rd party system.

1. The URL * field: the API reference will be provided by the 3rd party system.

2. The Nested Object field: add a value here if you would like to select a nested object in the response.

Example: You would enter results if you would like to select the results array from a search query response: { "results": [ { "Key": "Test", "Value": true } ], "_self": "api:v2/test" }

3. The Paged? Checkbox: Enable this option if you would like to page the results. This is generally recommended and will usually improve performance.

If the Paged? Checkbox is enabled the following text input fields and a checkbox will be displayed:

• Starting Page No*: This value will be used in the query as the page, offset or skip query parameters.

• Page Size*: This value will be used in the query as the limit or top of the query parameters.

• Skip Records? Checkbox: Enable this option if the API skips/offsets records, rather than incrementing page numbers.

• Parameters: If paging is enabled, the following parameters are required int the URL:

  • @PAGESIZE: Indicates the page size. To be used with limit or top query parameters.

  • @PAGENO: indicates the paging position. To be used with page, offset or skip query parameters.

Example: api/v2/configuration-item?$select=Ref,Name,Description&$filter=Name==@SEARCHTEXT&$top=@PAGESIZE&$skip=@PAGENO

Query Search

This query will be used when searching external sources. The query should filter resources by name.

1. Access ASM Menu>Search>External resources to search for a Connector, a Source, Resource Type and Resource, bringing back a live view of the 3rd party system.

2. The URL * field: the API reference will be provided by the 3rd party system.

3. The Nested Object field: add a value here if you would like to select a nested object in the response.

Example: You would enter results if you would like to select the results array from a search query response: { "results": [ { "Key": "Test", "Value": true } ], "_self": "api:v2/test" }

4. The Paged? Checkbox: Enable this option if you would like to page the results. This may improve performance. If paging is enabled, the following parameters are required int the URL:

@PAGESIZE: Indicates the page size. To be used with limit or top query parameters.

@PAGENO: indicates the paging position. To be used with page, offset or skip query parameters.

Example: api/v2/configuration-item?$select=Ref,Name,Description&$filter=Name==@SEARCHTEXT&$top=@PAGESIZE&$skip=@PAGENO

5. Starting Page No*: This value will be used in the query as the page, offset or skip query parameters.

6. Page Size*: This value will be used in the query as the limit or top of the query parameters.

7. Skip Records? Checkbox: Enable this option if the API skips/offsets records, rather than incrementing page numbers.

8. Parameters: @SEARCHTEXT: Use this parameter to filter resources by name.

Query Retrieve

This query will be used when retrieving a single resource item. It reflects the details that are brought back when you select a single individual item.

1. The URL * field: the API reference will be provided by the 3rd party system.

2. The Nested Object field: add a value here if you would like to select a nested object in the response.

Example: You would enter results if you would like to select the results array from a search query response: { "results": [ { "Key": "Test", "Value": true } ], "_self": "api:v2/test" }

3. The Paged? Checkbox: Enable this option if you would like to page the results. This may improve performance. If paging is enabled, the following parameters are required:

• Starting Page No*: This value will be used in the query as the page, offset or skip query parameters.

• Page Size*: This value will be used in the query as the limit or top of the query parameters.

• Skip Records? Checkbox: Enable this option if the API skips/offsets records, rather than incrementing page numbers.

4. UNIQUEID: This parameter is required and will be the unique id of source.

If paging is enabled, the following parameters are required int the URL: api/v2/configuration-item/@UNIQUEID

Resource Unique Identifier Field

The Field ID value needs to be the JSON attribute of the resource unique ID.

1. Field ID*: unique identifier of what gets returned

2. Data Type*: specifies which type of value a variable has and what type of mathematical, relational, or logical operation can be applied and chosen from the from the dropdown list: Blob, Boolean, DateTime, Float, GUID, Integer, Long, Password, String, Text.

Data Type	Used for	Example
Blob	Stores binary data as a single entity	Images, Audio, Multimedia objects, etc
Boolean	Representing logical values	TRUE, FALSE
DateTime	Stores an instant in time expressed as a calendar date and time of the day	YYYY-MM-DDThh:mm:ss, etc
Float (Real)	Numeric variable which includes all the integer numbers plus their fractions or decimals	3.15, 9.06, 00.13
GUID	Text string that represents and identification (Globally unique identifier)	ID software, hardware, documents, etc.
Integer	Numeric variable without a decimal-whole numbers	7,12, 999
Long	Used when you need a range of values more than those provided by Integer
Password	Represents a password value
String	Holds a list of characters of any length. Therefore, it can represent alphanumeric data and symbols	Hello world, Alice, Bob123

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