Technical documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Add CMDB Nodes ======

This user guide explains how to set-up a quick method for adding CMDB nodes in bulk using the CSV API.

A separate guide on the [[menu:operate:apis:csv_api|CSV API]] tool is also available.

The CSV API can be used to cut-and-paste rows of separated values to execute tasks on NetYCE objects. Adding and removing CMDB nodes are simple examples on two of these tasks for CMDB nodes.

A couple of items need to be setup initially make these tasks available to any NetYCE user and tailor them to your needs or design.

===== Setup =====

==== Permissions ====

As a first, access permissions to the CMDB client-type is required. Without CMDB access the setup or use of the created tasks will be denied.

Go to "Admin - Users & Groups - User-groups" and verify the appropriate groups have at least 'Engineer' level permissions for the CMDB Client type.


==== Service Types ====

Two short service types need to be created or can be imported using the files in the download section at the bottom. They can be tailored to your needs afterwards if needed.

Download these files and go to "Design - Service types" and import each. The **addCmdbNode** will create six lines to create a CMDB bode with a hostname, its fqdn, vendor-type and management domain. The **delCmdbNode** consists of a single line that just drops a node by hostname.

  Sty - CMDB - generic - api - addcmdbnode.xml
  Sty - CMDB - generic - api - delcmdbnode.xml

{{:guides:user:cmsb_service_types.png?800|}}


==== CSV API definitions ====

With the service types in place that are suitable for the regular NetYCE XCH API calls, an additional step can be taken to allow these to be used in the CSV API. The CSV API is essentially a wrapper around the XCH API that simplifies common API tasks for bulk processing where the relevant data is already available in table format - like Excel.

The added servicetypes to add and delete CMDB nodes obviously fall into this category. To make these suitable for the CSV API, a mapping of the variables needed for the service-type to a CSV format needs to be created. This is done in the ''etc/csv_api.ini'' configuration file which can be edited in the NetYCE GUI using the tool "Admin - Setup - Edit sys configs". The **YCE CSV API** configuration entry edits this file.

Add the entries below in this file and save it. This definition is all that is needed to use the CSV API.

The ''csv_api.ini'' entries:
<code>
[addCmdbNode]
brief = Add cmdb node to service - addcmdbnode | CMDB | generic | api | addcmdbnode
order = 1
node        # the node short hostname
vendor      # the node vendor_type. Use NetYCE vendor names
fqdn        # the node full-qualified-name or ipv4 address
domain      # the management domain

[delCmdbNode]
brief = Add cmdb node to service - delcmdbnode | CMDB | generic | api | delcmdbnode
order = 2
node
</code>


===== Using the CSV API =====

To add or remove a batch of nodes from the CMDB, go to the "Operate - API's - CSV  API" tool. The large text-box already shows the available definitions as comments to clarify their use, mostly the fields required and their order.

You type or just can just paste in the CSV lines with the desired actions. Often an Excel sheet is used as the basis for these lines.

The tool auto-detects the field separator used (tab, comma, semicolon or vertical-bar. For readability spaces around the separator are ignored.

The sample below could be pasted in to add four and remove two nodes:

<code>
# Preamble is included with ALL api-types
#   <PRE> = client_type | service_class | service_type | service_task
# example: 'newClient | YCE | api | api | newclient | ESXi'


# addCmdbNode
# Add cmdb node to service - addcmdbnode | CMDB | generic | api | addcmdbnode
# addCmdbNode | <PRE> | node | vendor | fqdn | domain

addCmdbNode | CMDB | generic | api | addCmdbNode | AMS-DC01-XC01 | Junos | ams-dc01-xc01.acme.com | ams-xc
addCmdbNode | CMDB | generic | api | addCmdbNode | AMS-DC01-XC02 | Junos | ams-dc01-xc02.acme.com | ams-xc
addCmdbNode | CMDB | generic | api | addCmdbNode | AMS-DC03-AC01 | Cisco_nexus | ams-dc03-ac01.acme.com | ams-ac
addCmdbNode | CMDB | generic | api | addCmdbNode | AMS-DC03-AC02 | Cisco_nexus | ams-dc03-ac02.acme.com | ams-ac



# delCmdbNode
# Add cmdb node to service - delcmdbnode | CMDB | generic | api | delcmdbnode

delCmdbNode | CMDB | generic | api | delCmdbNode | UTR-DC02-AC03 
delCmdbNode | CMDB | generic | api | delCmdbNode | UTR-DC02-AC04 
</code>

When submitting these records a summary is shown before actual execution. Errors are flagged and corrections can be made.

{{:guides:user:csv_api_adding_cmdb_nodes.png?800|}}


Each line is executed in succesion. Any failures due to incorrect service-type or unknown references halt the execution to allow corrections. The example below shows such a failure as the referenced Domain does not exist.

{{:guides:user:csv_api_error_report.png?600|}}

After correcting the error, the execution is restarted (skipping previously successful), resulting in the regular progress report.

{{:guides:user:csv_api_execution.png?600|}}


===== Download =====

<file xml Sty - CMDB - generic - api - addcmdbnode.xml>
<export>
  <Client_types name="CMDB"
                Client_type="CMDB"
                Client_type_name="CMDB nodes"
                Plan_id="-1"
                Plan_id_description=""
                Plan_prefix="0"
                Timestamp="2020-01-08 11:06:40" />
  <Export Client_type="CMDB"
          Service_class="generic"
          Service_task="addcmdbnode"
          Service_type="api"
          Type="Service_type" />
  <Origin Customer=""
          Database_patch="22020901"
          Database_version="8.0.0"
          Date="Fri Feb 18 17:54:15 CET 2022"
          Exporter_version="2"
          Operator="yce"
          Server="devel7a" />
  <Service_class name="CMDB"
                 Client_type="CMDB"
                 Hierarchy_id="100"
                 Image_name="CMDB_CMDB_CMDB"
                 Image_position=""
                 Service_caption="CMDB"
                 Service_class="generic"
                 Service_class_limit="0"
                 Site_type="CMDB"
                 Timestamp="2020-01-08 11:06:40" />
  <Service_types name="0001"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2020-01-08 11:06:40"
                 Type_alias="&lt;client&gt;"
                 Type_class="CLIENT"
                 Type_description=""
                 Type_exec="LOCATE"
                 Type_match="CLIENT_CODE"
                 Type_scope="CURRENT"
                 Type_seq="1"
                 Type_value="CMDB"
                 Type_value2=""
                 Type_value3="" />
  <Service_types name="0002"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2020-01-08 11:06:40"
                 Type_alias="&lt;site&gt;"
                 Type_class="SITE"
                 Type_description=""
                 Type_exec="LOCATE"
                 Type_match="SITE_CODE"
                 Type_scope="&lt;client&gt;"
                 Type_seq="2"
                 Type_value="CMDB"
                 Type_value2=""
                 Type_value3="" />
  <Service_types name="0003"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2022-02-18 17:43:31"
                 Type_alias="&lt;dom&gt;"
                 Type_class="DOMAIN"
                 Type_description=""
                 Type_exec="LOCATE"
                 Type_match="DOMAIN_NAME"
                 Type_scope="GLOBAL"
                 Type_seq="3"
                 Type_value="(domain)"
                 Type_value2=""
                 Type_value3="" />
  <Service_types name="0004"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2020-01-08 11:06:40"
                 Type_alias="&lt;node&gt;"
                 Type_class="CMDB"
                 Type_description=""
                 Type_exec="ADD"
                 Type_match="NODE"
                 Type_scope="&lt;dom&gt;"
                 Type_seq="4"
                 Type_value="(node)"
                 Type_value2=""
                 Type_value3="" />
  <Service_types name="0005"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2020-01-08 11:06:40"
                 Type_alias=""
                 Type_class="CMDB"
                 Type_description=""
                 Type_exec="ASSIGN"
                 Type_match="FQDN"
                 Type_scope="&lt;node&gt;"
                 Type_seq="5"
                 Type_value="(fqdn)"
                 Type_value2=""
                 Type_value3="" />
  <Service_types name="0006"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="addcmdbnode"
                 Service_type="api"
                 Timestamp="2020-01-08 11:06:40"
                 Type_alias=""
                 Type_class="CMDB"
                 Type_description=""
                 Type_exec="ASSIGN"
                 Type_match="VENDOR"
                 Type_scope="&lt;node&gt;"
                 Type_seq="6"
                 Type_value="(vendor)"
                 Type_value2=""
                 Type_value3="" />
  <Site_types name="CMDB"
              Client_type="CMDB"
              Client_type_limit="0"
              Image_name="CMDB_CMDB_topo"
              Image_position=""
              SiteType="1500"
              Site_caption="CMDB"
              Site_class="CMDB A"
              Site_class_limit="0"
              Site_name_format=""
              Site_type="CMDB"
              Timestamp="2020-01-08 11:06:40" />
</export>
</file>


<file xml Sty - CMDB - generic - api - delcmdbnode.xml>
<export>
  <Client_types name="CMDB"
                Client_type="CMDB"
                Client_type_name="CMDB nodes"
                Plan_id="-1"
                Plan_id_description=""
                Plan_prefix="0"
                Timestamp="2020-01-08 11:06:40" />
  <Export Client_type="CMDB"
          Service_class="generic"
          Service_task="delcmdbnode"
          Service_type="api"
          Type="Service_type" />
  <Origin Customer=""
          Database_patch="22020901"
          Database_version="8.0.0"
          Date="Fri Feb 18 17:54:19 CET 2022"
          Exporter_version="2"
          Operator="yce"
          Server="devel7a" />
  <Service_class name="CMDB"
                 Client_type="CMDB"
                 Hierarchy_id="100"
                 Image_name="CMDB_CMDB_CMDB"
                 Image_position=""
                 Service_caption="CMDB"
                 Service_class="generic"
                 Service_class_limit="0"
                 Site_type="CMDB"
                 Timestamp="2020-01-08 11:06:40" />
  <Service_types name="0001"
                 Client_type="CMDB"
                 Service_class="generic"
                 Service_task="delcmdbnode"
                 Service_type="api"
                 Timestamp="2022-02-18 17:51:33"
                 Type_alias="&lt;site&gt;"
                 Type_class="CMDB"
                 Type_description=""
                 Type_exec="DELETE"
                 Type_match="NODE"
                 Type_scope="CMDB"
                 Type_seq="1"
                 Type_value="&lt;node&gt;"
                 Type_value2=""
                 Type_value3="" />
  <Site_types name="CMDB"
              Client_type="CMDB"
              Client_type_limit="0"
              Image_name="CMDB_CMDB_topo"
              Image_position=""
              SiteType="1500"
              Site_caption="CMDB"
              Site_class="CMDB A"
              Site_class_limit="0"
              Site_name_format=""
              Site_type="CMDB"
              Timestamp="2020-01-08 11:06:40" />
</export>
</file>