View Source

From verison 2.x on, iDNA Applications provides an external API for the following scenarios:

With the API you can extract database and replica set information collected by iDNA Applications to use it in other applications
With the API you can assign or update custom properties to databases or replica sets so that you can use them within iDNA Applications.

Postman

Use the Postman collection to test the API calls.

Note that you have to set the host variable in the postman (under settings → manage environments).

The external API is located under https:/<IFA_host_name>/api/external/xxx

Authorization

A user is required which can be created under https:/<IFA_host_name>/idna/sys/accounts

iDNA Applications > API Documentation - Catalog & Custom Properties > MicrosoftTeams-image.png

Please note that you have to select "API" from the Authority drop down list.

In order to use the API an authorization header needs to be sent. We are using Basic Authentication, so the header should look like this:

if your credentials are for example user:password

Authorization: Basic dXNlcjpwYXNzd29yZA==

the API returns 401 if

No Authorization header is provided
User credentials are wrong
User Authority is insufficient

Database Instances

Description

URL

Payload

Response

Response Json

Get a list of all databases

GET {{host}}/api/external/databases

Parameters:

focus - boolean: filter focus databases

e.g.: {{host}}/api/external/databases?focus=true

-

Returns an array of database objects with basic information.

[
	{
        "res_id": 469,
        "server_name": "server/panagenda",
        "file_name": "test/testlog.nsf",
        "title": "iDNAlog",
        "replicaid": "C1245D0E15534F18",
        "database_type": "Application",
        "size_bytes": "1290240",
        "is_focus_db": true
    }
]

Get a list of all databases with custom properties

GET {{host}}/api/external/databases/all/customProperties

Parameters:

resIds - string: comma separated list of res_id values that can be used to select specific databases

e.g.: {{host}}/api/external/databases/all/customProperties?resIds=402,403,404

-

Returns an array of database objects with custom properties

{
        "res_id": 330,
        "customProperties": {
            "ts": "2020-06-03T21:06:14.217848+00:00",
            "source": "web",
            "values": {
                "1001001": "Dormant",
                "1001002": "Cher",
                "1001003": "classification",
                "1001004": "Yes",
                "1001005": "Low",
                "1001006": "435",
                "1001008": "Development",
                "1001009": "user@panagenda.com",
                "1001010": "developer@panagenda.com",
                "1001011": "known interfaces",
                "1001012": "Mars",
                "1001013": "www.google.com",
                "1001014": 1593180000000,
                "1001020": "comment"
            },
            "comment": null,
            "modifier": "config"
        }
    },

Get a list of all databases with detailed information

GET {{host}}/api/external/databases/all/details

Parameters:

resIds - string: comma separated list of res_id values that can be used to select specific databases

e.g.: {{host}}/api/external/databases/all/details?resIds=402,403,404

-

Returns an array of database objects with detailed information (including custom properties)

 {
        "usage": null,
        "views": null,
        "design": null,
        "res_id": 402,
        "catalog": {
            "id": 402,
            "size": 3932160,
            "type": 0,
            "title": "Domino Change Control (6)",
            "server": {
                "node_id": 6,
                "hostname": "test.somedomain.com",
                "data_path": "D:/Domino/Data",
                "exec_path": "C:/Domino/Server/",
                "server_os": "Windows/2003 5.2 Intel Pentium",
                "servername": "server/panagenda",
                "clustername": null,
                "server_tags": [
                    "panagenda"
                ],
                "domino_version": "Release 8.5.3FP6 HF646",
                "collection_active": true,
                "domino_buildnumber": "390",
                "max_collection_date": "2020-05-11",
                "min_collection_date": "2016-06-12",
                "server_architecture": "32 Bit",
                "tasks_running_count": 15,
                "server_access_status": 0
            },
            "created": 1089210821000,
            "size_mb": 3.8,
            "filename": "filename.ntf",
            "licensed": true,
            "modified": 1591521362406.52,
            "best_type": null,
            "replicaid": "85256AE30062503A",
            "sizequota": 0,
            "act_period": 3009,
            "categories": null,
            "in_catalog": true,
            "odsversion": null,
            "volumename": "D",
            "act_dayuses": 0,
            "is_focus_db": false,
            "percentused": 0,
            "sizewarning": 0,
            "storagepath": "D:\\Domino\\Data\\filename.ntf",
            "act_dayreads": 0,
            "act_weekuses": 0,
            "created_date": "2004-07-07",
            "lastmodified": 1588998889000,
            "templatename": "DominoChangeControl",
            "act_daywrites": 0,
            "act_monthuses": 1,
            "act_weekreads": 0,
            "documentcount": 78,
            "acl_adminnames": false,
            "act_monthreads": 0,
            "act_perioduses": 80,
            "act_weekwrites": 0,
            "count_replicas": 13,
            "filename_lower": "domchange.ntf",
            "in_dbdirectory": true,
            "server_node_id": 6,
            "type_on_server": 300,
            "act_monthwrites": 14,
            "act_periodreads": 0,
            "design_modified": 1397774744000,
            "fulltextindexed": false,
            "identified_type": 300,
            "listindbcatalog": true,
            "acl_author_count": 0,
            "acl_editor_count": 0,
            "acl_reader_count": 1,
            "act_periodwrites": 1082,
            "cat_doc_modified": 1591140117000,
            "created_datetime": "2004-07-07T14:33:41+00:00",
            "idna_instance_id": 6699374546818320000,
            "log_doc_modified": 1591498842000,
            "acl_manager_count": 4,
            "inmultidbindexing": false,
            "acl_designer_count": 0,
            "acl_noaccess_count": 5,
            "designtemplatename": null,
            "acl_depositor_count": 0,
            "design_num_documents": 182,
            "replication_disabled": false,
            "replication_priority": 2,
            "is_template_candidate": true,
            "acl_defaultaccesslevel": 2,
            "db_usage_history_start": null,
            "db_usage_history_until": null,
            "idna_domino_catalog_id": 7862820,
            "design_collection_state": "Not Collected",
            "acl_administrationserver": null,
            "acl_anonymousaccesslevel": 0,
            "best_type_server_node_id": null,
            "created_catalog_datetime": "2004-07-07T14:33:41+00:00",
            "replication_cutoffdelete": false,
            "replication_ignoredeletes": true,
            "db_usage_history_available": false,
            "replication_cutoffinterval": 0,
            "server_max_collection_date": "2020-05-11",
            "server_min_collection_date": "2016-06-12",
            "replication_receivesummaries": false,
            "replication_sendtitleandcatalog": true,
            "desgin_minimum_addedtofile_datetime": null,
            "usage_collection_log_sessions_start": 1465689600000,
            "usage_collection_log_sessions_until": 1589155200000
        },
        "insights": null,
        "similarity": null,
        "customProperties": {
            "ts": "2020-06-08T07:47:05.162921+00:00",
            "source": "external-api",
            "values": {
                "1001004": "Yes",
                "1001005": "Very High",
                "1001009": "NodeJs"
            },
            "comment": null,
            "modifier": null
        }
    }

ReplicaSets

Description

URL

Payload

Response

Response Json

Get a list of all replica sets

GET {{host}}/api/external/replicaSets

Parameters:

focus - boolean: filter focus databases

e.g.: {{host}}/api/external/replicaSets?focus=true

-

Returns an array of replica set objects with basic information

[
	{
        "replicaid": "C14576C5113CCE73",
        "title": "",
        "server_names": [
            "server/panagenda"
        ],
        "replicas_count": 1,
        "db_type_name": "System Database",
        "is_focus_db": false
    }
]

Get a list of all replica sets with custom properties

GET {{host}}/api/external/replicaSets/all/customProperties

Parameters:

replicaIds- string: comma separated list of replicaid values that can be used to select specific replica sets

e.g.: {{host}}/api/external/databases/all/customProperties?replicaIds=C2357E4B127EDE78,C23579AE0125A4B3,C2258814004555A9

-

Returns an array of replica set objects with custom properties

[
	{
        "replicaid": "C14576C5113CCE73",
        "customProperties": {
            "ts": "2020-06-08T10:01:39.29916+00:00",
            "values": {
                "1002009": "Very High",
                "1002012": "NodeJS"
            },
            "comment": null,
            "modifier": null,
            "resource": "external-api"
        }
    }
]

Get a list of all replica sets with detailed information

GET {{host}}/api/external/replicaSets/all/details

Parameters:

replicaIds- string: comma separated list of replicaid values that can be used to select specific replica sets

e.g.: {{host}}/api/external/databases/all/details?replicaIds=C2357E4B127EDE78,C23579AE0125A4B3,C2258814004555A9

-

Returns an array of replica set objects with detailed information (including custom properties)

[
	{
        "title": "",
        "replicaid": "C14576C5113CCE73",
        "db_type_id": 300,
        "db_type_name": "System Database",
        "is_focus_db": false,
        "design_collection_status": "Not Collected",
        "design_collection_status_detail": "Not Collected",
        "replicas_count": 1,
        "replicas_encrypted_count": 0,
        "server_names": [
            "server/panagenda"
        ],
        "replica_paths": [
            "server/panagenda!!filename.nsf"
        ],
        "server_adminserver": null,
        "categories": null,
        "application_created_date": "2010-04-29",
        "application_lastmodified_date": "2020-06-06",
        "db_usage_history_start_date": null,
        "usage_collection_log_sessions_start_date": "2017-03-08",
        "usage_collection_log_sessions_until_date": "2020-05-29",
        "last_accessed": null,
        "last_accessed_user": null,
        "last_accessed_on_server": null,
        "last_write_access": null,
        "last_write_user": null,
        "usage_category_simplified": "No / Low",
        "usage_display_index": 0,
        "usage_all_time": "No Usage",
        "user_access_days_all_time": 0,
        "users_active_all_time": 0,
        "days_active_all_time": 0,
        "sessions_all_time": 0,
        "sessions_web_all_time": 0,
        "sessions_write_all_time": 0,
        "usage_last365d": "No Usage",
        "user_access_days_last365d": 0,
        "users_active_last365d": 0,
        "days_active_last365d": 0,
        "sessions_last365d": 0,
        "sessions_web_last365d": 0,
        "sessions_write_last365d": 0,
        "usage_last90d": "No Usage",
        "user_access_days_last90d": 0,
        "users_active_last90d": 0,
        "days_active_last90d": 0,
        "sessions_last90d": 0,
        "sessions_web_last90d": 0,
        "sessions_write_last90d": 0,
        "usage_last30d": "No Usage",
        "user_access_days_last30d": 0,
        "users_active_last30d": 0,
        "days_active_last30d": 0,
        "sessions_last30d": 0,
        "sessions_web_last30d": 0,
        "sessions_write_last30d": 0,
        "usage_last7d": "No Usage",
        "user_access_days_last7d": 0,
        "users_active_last7d": 0,
        "days_active_last7d": 0,
        "sessions_last7d": 0,
        "sessions_web_last7d": 0,
        "sessions_write_last7d": 0,
        "documents_count_min": 48,
        "documents_count_avg": 48,
        "documents_count_max": 48,
        "size_mb_min": 67,
        "size_mb_avg": 67.5,
        "size_mb_max": 67,
        "design_complexity": "Not Analyzed",
        "design_complexity_simplified": "Not Analyzed",
        "design_complexity_score": null,
        "design_complexity_display_index": 0,
        "design_insights_score": null,
        "is_template_candidate": false,
        "templates_inherits_from_count": 1,
        "templates_inherits_from": [
            "StdR85Mail"
        ],
        "templates_acts_as_master_count": 0,
        "templates_acts_as_master": null,
        "remediation_classification": null,
        "remediation_display_index": null,
        "design_consistency": "OK",
        "design_age_difference_hours": 0,
        "design_modified_newest_design": "2015-11-10T00:00:57+00:00",
        "design_modified_oldest_design": "2015-11-10T00:00:57+00:00",
        "database_id_newest_design": 72,
        "replica_newest_design": "server/panagenda!!filename.nsf",
        "database_id_oldest_design": 72,
        "replica_oldest_design": "server/panagenda!!filename.nsf",
        "most_similar_template_name_newest_design": null,
        "most_similar_template_similarity_newest_design": null,
        "most_similar_template_name_oldest_design": null,
        "most_similar_template_similarity_oldest_design": null,
        "design_is_similar_to_standard_template": null,
        "template_similarity_ranking_list": null,
        "design_cluster_count": null,
        "design_cluster_ids": null,
        "database_id_design_reference": null,
        "design_formula_elements": null,
        "design_formula_loc": null,
        "design_lotusscript_elements": null,
        "design_lotusscript_loc": null,
        "design_javascript_elements": null,
        "design_javascript_loc": null,
        "design_java_elements": null,
        "design_java_loc": null,
        "design_agents_elements": null,
        "design_agents_loc": null,
        "design_folders_elements": null,
        "design_folders_loc": null,
        "design_forms_elements": null,
        "design_forms_loc": null,
        "design_views_elements": null,
        "design_views_loc": null,
        "design_scriptlibraries_elements": null,
        "design_scriptlibraries_loc": null,
        "design_xpages_elements": null,
        "design_xpages_customcontrols": null,
        "mailin_names": null,
        "customProperties": {
            "ts": "2020-06-08T10:01:39.29916+00:00",
            "values": {
                "1002009": "Very High",
                "1002012": "NodeJS"
            },
            "comment": null,
            "modifier": null,
            "resource": "external-api"
        }
    }
]

Custom Properties

Description

URL

Payload

Response

Response Json

Get all custom properties

GET {{host}}/api/external/customProperties

Parameters:

type - string: can be used to filter for database ('db') or replica set ('rs') custom properties

e.g.:

{{host}}/api/external/customProperties?type=rs

{{host}}/api/external/customProperties?type=db

-

Returns an array of custom property objects

[
	{
        "type": "db",
        "id": 33,
        "name": "1241234",
        "metadata_type": "text",
        "options": {
            "values": []
        },
        "created_by": "config",
        "description": null,
        "custom": true,
        "enabled": false
    },
	{
        "type": "rs",
        "id": 1002004,
        "name": "VIP Attention",
        "metadata_type": "oneof",
        "options": {
            "values": [
                "Yes",
                "No"
            ]
        },
        "created_by": "panagenda",
        "description": null,
        "custom": false,
        "enabled": true
    }
]

Custom Property Assignments

Description

URL

Payload

Response

Response Json

Assign x custom properties to y databases

POST {{host}}/api/external/customPropertyAssignment/database

Headers:

Content-Type: application/json

{
	"targetIds": [402, 403, 404],
	"customProperties": {
		"1001009": "NodeJs",
		"1001005": "Very High"
	}
}

targetIds - comma separated list of database res_id values

customProperties - an object with key / value pairs of custom property id and custom property value

updated - An array of created / updated custom properties

error - Contains error information. e.g. if certain targetIds does not exist

{
    "updated": [
        {
            "res_id": 402,
            "customProperties": {
                "ts": "2020-06-08T13:20:05.541693+00:00",
                "source": "external-api",
                "values": {
                    "1001004": "Yes",
                    "1001005": "Very High",
                    "1001009": "NodeJs"
                },
                "comment": null,
                "modifier": null
            }
        },
        {
            "res_id": 404,
            "customProperties": {
                "ts": "2020-06-08T13:20:05.541693+00:00",
                "source": "external-api",
                "values": {
                    "1001004": "Yes",
                    "1001005": "Very High",
                    "1001009": "NodeJs"
                },
                "comment": null,
                "modifier": null
            }
        },
        {
            "res_id": 403,
            "customProperties": {
                "ts": "2020-06-08T13:20:05.541693+00:00",
                "source": "external-api",
                "values": {
                    "1001004": "Yes",
                    "1001005": "Very High",
                    "1001009": "NodeJs"
                },
                "comment": null,
                "modifier": null
            }
        }
    ],
    "error": {
        "message": "The following resources were not updated because the ids does not exist",
        "notUpdated": [
            9999
        ]
    }
}

Assign x custom properties to y replica sets

POST {{host}}/api/external/customPropertyAssignment/replicaSet

Headers:

Content-Type: application/json

{
	"targetIds": ["C2357E4B127EDE78", "C23579AE0035A477", "C2357714004455A9"],
	"customProperties": {
		"1001009": "NodeJs",
		"1001005": "Very High"
	}
}

targetIds - comma separated list of replicaset replicaid values

customProperties - an object with key / value pairs of custom property id and custom property value

updated - An array of created / updated custom properties

error - Contains error information. e.g. if certain targetIds does not exist

{
    "updated": [
        {
            "replicaid": "C2357E4B127EDE78",
            "customProperties": {
                "ts": "2020-06-08T13:24:37.128571+00:00",
                "values": {
                    "1002009": "Very High",
                    "1002012": "NodeJS"
                },
                "comment": null,
                "modifier": null,
                "resource": "external-api"
            }
        },
        {
            "replicaid": "C23579AE0035A477",
            "customProperties": {
                "ts": "2020-06-08T13:24:37.128571+00:00",
                "values": {
                    "1002009": "Very High",
                    "1002012": "NodeJS"
                },
                "comment": null,
                "modifier": null,
                "resource": "external-api"
            }
        },
        {
            "replicaid": "C2357714004455A9",
            "customProperties": {
                "ts": "2020-06-08T13:24:37.128571+00:00",
                "values": {
                    "1002009": "Very High",
                    "1002012": "NodeJS"
                },
                "comment": null,
                "modifier": null,
                "resource": "external-api"
            }
        }
    ],
    "error": {
        "message": "The following resources were not updated because the ids does not exist",
        "notUpdated": [
            "C1257E4B007EDEAA"
        ]
    }
}