API Format Changes - 7800

API Format Changes - 7800

API Format Changes - 7800

This document outlines the differences between the old and new API formats for CI relationships.
The new API format will be applicable for customers who have upgraded to build 7800 of AssetExplorer. We recommend using the new formats for all new integrations.

Key Changes in API Format 

  1. The UDF holder fields, such as cm_fields and udf_fields, are removed from CI relationship APIs.
  2. Backward compatibility is supported for CI relationship APIs.
  3. Naming conventions for additional fields have been standardized:
    1. Default Modules:  
      1. API field names now follow the format udf_<user input>.
      2. This update applies to the following modules: User, Technician, CMDB, Release, Project, Worklog, Task, Space, Facility, Vendor, CI Type Association, Asset, Support Groups, and Department.
Old Format
New Format
udf_<field_type>_<user_input> (Example: udf_date_date_of_birth)
or,
<field_type>_<user_input> (Example: date_date_of_birth)
udf_<user input> (Example: udf_date_of_birth)

 CI Relationship API  

Method
URL
Old Format
New Format
POST
/api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations 
 
input_data:
{  "assoc_apache_connected_to_windows_workstations": [
    {
      "destination": {
        "id": "2"
      },
      "udf_fields": {
        "udf_source_no": "001",
        "udf_technician": {
          "id": "5"
        }
      }
    }
  ]
}
input_data:
{  "assoc_apache_connected_to_windows_workstations": [
    {
      "destination": {
        "id": "2"
      },
        "udf_source_no": "001",
        "udf_technician": {
          "id": "5"
      }
    }
  ]
}
GET_ALL
/api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations
Sample Response:
{
  "response_status": [
    {
      "status_code": 2000,
      "status": "success"
    }
  ],
  "assoc_apache_connected_to_windows_workstations": [
    {
      "udf_fields": {
        "udf_source_no": "001",
        "udf_technician": {
          "email_id": null,
          "phone": "1234455",
          "name": "administrator",
          "mobile": "1234567890",
          "profile_pic": {
            "content-url": "/images/default-profile-pic2.svg"
          },
          "is_vipuser": false,
          "id": "5",
          "department": null
        }
      },
      "destination": {
        "site": null,
        "inactive": false,
        "module": {
          "id": "190"
        },
        "name": "windows workstation",
        "id": "2",
        "entity": {
          "api_plural_name": "cmdb_windows_workstation",
          "name": "cmdb_windows_workstation",
          "icon": {
            "id": "410"
          },
          "id": "190",
          "display_name": "Windows Workstation",
          "display_plural_name": "Windows Workstation",
          "category": {
            "id": "18"
          }
        },
        "status": null
      },
      "id": "2",
      "association_type": {
        "name": "Connected to",
        "id": 3
      }
    }
  ],
  "list_info": {
    "has_more_rows": false,
    "start_index": 1,
    "row_count": 1
  }
}
Sample Response:
{
  "response_status": [
    {
      "status_code": 2000,
      "status": "success"
    }
  ],
  "assoc_apache_connected_to_windows_workstations": [
    {
        "udf_source_no": "001",
        "udf_technician": {
          "email_id": null,
          "phone": "1234455",
          "name": "administrator",
          "mobile": "1234567890",
          "profile_pic": {
            "content-url": "/images/default-profile-pic2.svg"
          },
          "is_vipuser": false,
          "id": "5",
          "department": null
        },
      "destination": {
        "site": null,
        "inactive": false,
        "module": {
          "id": "190"
        },
        "name": "windows workstation",
        "id": "2",
        "entity": {
          "api_plural_name": "cmdb_windows_workstation",
          "name": "cmdb_windows_workstation",
          "icon": {
            "id": "410"
          },
          "id": "190",
          "display_name": "Windows Workstation",
          "display_plural_name": "Windows Workstation",
          "category": {
            "id": "18"
          }
        },
        "status": null
      },
      "id": "2",
      "association_type": {
        "name": "Connected to",
        "id": 3
      }
    }
  ],
  "list_info": {
    "has_more_rows": false,
    "start_index": 1,
    "row_count": 1
  }
}
 

 Backward Compatibility Changes 

Backward compatibility support will be discontinued from the next feature release. We recommend updating to the new API format and adjusting GlobalConfig accordingly. 
During migration, the API names of existing CI relationships are set to the paramvalue attribute in GlobalConfig.
<GlobalConfig helpdeskid="IT Helpdesk" globalconfigid="GlobalConfig:globalconfigid:120001" category="CM_BACKWARD_COMPATIBILITY" parameter="CM_MODULES_LIST" paramvalue="<entity_api_name>" description="To support backward compatibility for old custom modules"/> 
A warning message will be displayed during migration, as shown:
After migration, a warning message will be displayed on the CI relationship details page for which backward compatibility is provided.

CI Relationships
Note:
  1. Python scripts, custom functions, custom widgets, field and form rules, custom scripts, and all external API access will continue to follow the old format until backward compatibility is removed i.e., until the module API name is removed from GlobalConfig.
  2. Only APIs triggered from AssetExplorer UI will follow the new format.

Managing Backward Compatibility

To add or remove modules from backward compatibility support, use the following query:
 update globalconfig set paramvalue ='<entity_api_name>' where category = 'CM_BACKWARD_COMPATIBILITY'; 
 

 
 

    • Related Articles

    • Asset API Changes

      Asset API This document outlines the differences between the deprecated V3 API and the new V3 API for the Assets module. The new V3 API is available for customers who have upgraded to build 15100 of ServiceDesk Plus or 7700 of AssetExplorer, and ...

    • CMDB and Asset Behavior Changes

      Behavior Changes This document outlines the behavior changes in the Assets and CMDB modules, applicable to customers migrating to build 15100 of ServiceDesk Plus and build 7700 of AssetExplorer. In this release, CMDB and Assets are treated as ...

    • CMDB API

      All product configuration items are accessible through the CMDB API. If one server relies on another server, the relationship between the two servers can also be established through the CMDB API. Key points: Add CIs using the URL format: ...

    • CMDB API V1 and V3 Comparison

      CMDB API This document outlines the differences between the deprecated V1 API and the new V3 API for CMDB in ServiceDesk Plus. The new V3 API is available for customers who have upgraded to build 15100 of ServiceDesk Plus or 7700 of AssetExplorer. We ...

    • Generate API Key

      Generate an API Key that can be used for third-party integrations. To generate the key, Click the profile icon and select Generate API Key. Select the expiry option - you can set the key to never expire or to expire after a specific period. Click ...