From 2a09e6bcd47c67db4f9107a6891623b56fdbb70e Mon Sep 17 00:00:00 2001 From: luke-hagar-sp <98849695+luke-hagar-sp@users.noreply.github.com> Date: Tue, 9 May 2023 11:48:27 -0500 Subject: [PATCH 1/2] Template Documentation --- products/idn/tools/cli/Templates/report.md | 80 ++++++++++++++ products/idn/tools/cli/Templates/search.md | 103 +++++++++++++++++++ products/idn/tools/cli/Templates/spconfig.md | 87 ++++++++++++++++ 3 files changed, 270 insertions(+) create mode 100644 products/idn/tools/cli/Templates/report.md create mode 100644 products/idn/tools/cli/Templates/search.md create mode 100644 products/idn/tools/cli/Templates/spconfig.md diff --git a/products/idn/tools/cli/Templates/report.md b/products/idn/tools/cli/Templates/report.md new file mode 100644 index 000000000..df2f197f0 --- /dev/null +++ b/products/idn/tools/cli/Templates/report.md @@ -0,0 +1,80 @@ +--- +id: cli-template-report +title: Report Template +pagination_label: CLI Templates Report +sidebar_label: Report +sidebar_position: 7 +sidebar_class_name: cli-template-report +keywords: ['cli', 'template', 'report'] +description: Learn about the CLI commands you can use to interact with VAs in this guide. +slug: /tools/cli/templates/report +tags: ['CLI'] +--- + +Use Report Templates to run a set of simple predefined search queries from the CLI Reports are most useful when you do not care about the search results returned from a query, and only want to know the Count of results. + +This is an example of a report template: + +```json +[ + { + "name": "provisioning-and-security", + "description": "All account unlocks in the tenant for a given time range", + "variables": [{"name": "days", "prompt": "Days before today"}], + "queries": [ + { + "queryString": "(type:provisioning AND created:[now-{{days}}d TO now])", + "queryTitle": "Provisioning Events for the last {{days}} days" + }, + { + "queryString": "(USER_UNLOCK_PASSED AND created:[now-{{days}}d TO now])", + "queryTitle": "User Unlocks for the last {{days}} days" + } + ] + } +] +``` + +This is the report template anatomy + +```json +[ + { + "name": "provisioning-and-security", +``` + +The Name of the search template. + +This is what will show up in the template list when running `sail report`. + +This is also the name you can provide as an argument `sail report provisioning-and-security` + +```json + "description": "All account unlocks in the tenant for a given time range", +``` + +The description of the report template, this will show below the template name in the `sail report` list + +```json + "variables": [{"name": "days", "prompt": "Days before today"}], +``` + +Variables are used to populate values in the content below dynamically during command run time for example the Variable in this template is configured so you can choose how many days back you want to search for provisioning-and-security events when you run `sail report provisioning-and-security` a prompt appears saying `Input Days before today:` the number you enter is then populated anywhere that variable is used in the below object, and the query is run + +```json + "queries": [ + { + "queryString": "(type:provisioning AND created:[now-{{days}}d TO now])", + "queryTitle": "Provisioning Events for the last {{days}} days" + }, + { + "queryString": "(USER_UNLOCK_PASSED AND created:[now-{{days}}d TO now])", + "queryTitle": "User Unlocks for the last {{days}} days" + } + ] + + } +] +``` + +This is a list of the queries that will be run, currently variables for days are populated diff --git a/products/idn/tools/cli/Templates/search.md b/products/idn/tools/cli/Templates/search.md new file mode 100644 index 000000000..e54a881de --- /dev/null +++ b/products/idn/tools/cli/Templates/search.md @@ -0,0 +1,103 @@ +--- +id: cli-template-search +title: Search Template +pagination_label: CLI Templates Search +sidebar_label: Search +sidebar_position: 7 +sidebar_class_name: cli-template-search +keywords: ['cli', 'template', 'search'] +description: Learn about the CLI commands you can use to interact with VAs in this guide. +slug: /tools/cli/templates/search +tags: ['CLI'] +--- + +Use Search Templates to run predefined search queries from the CLI + +This is an example of a template file with 3 search templates populated + +```json +[ + { + "name": "all-account-unlocks", + "description": "All account unlocks in the tenant for a given time range", + "variables": [{"name": "days", "prompt": "Days before today"}], + "searchQuery": { + "indices": ["events"], + "queryType": null, + "queryVersion": null, + "query": { + "query": "(USER_UNLOCK_PASSED AND created:[now-{{days}}d TO now])" + }, + "sort": [], + "searchAfter": [] + } + }, + { + "name": "all-provisioning-events", + "description": "All provisioning events in the tenant for a given time range", + "variables": [{"name": "days", "prompt": "Days before today"}], + "searchQuery": { + "indices": ["events"], + "queryType": null, + "queryVersion": null, + "query": { + "query": "(type:provisioning AND created:[now-{{days}}d TO now])" + }, + "sort": [], + "searchAfter": [] + } + }, + { + "name": "all-provisioning-events-90-days", + "description": "All provisioning events in the tenant for a given time range", + "variables": [], + "searchQuery": { + "indices": ["events"], + "queryType": null, + "queryVersion": null, + "query": { + "query": "(type:provisioning AND created:[now-90d TO now])" + }, + "sort": [], + "searchAfter": [] + } + } +] +``` + +This is the search template anatomy: + +```json +{ + "name": "all-account-unlocks", +``` + +The search template name that displays in the template list when you run `sail search template`. + +You can also provide this name as an argument: `sail search template all-account-unlocks` + +```json + "description": "All account unlocks in the tenant for a given time range" +``` + +The search template description that displays below the template name in the `sail search template` list + +```json + "variables": [{"name": "days", "prompt": "Days before today"}], +``` + +Use variables to dynamically populate values in the following content during command run time. For example, the variable in this template is configured such that you can choose how many days back you want to search for account unlock events. When you run `sail search template all-account-unlocks`, a prompt displays, saying `Input Days before today:` The number you enter is then populated anywhere that variable is used in the following object, and the query runs. + +```json + "searchQuery": { + "indices": ["events"], + "queryType": null, + "queryVersion": null, + "query": { + "query": "(USER_UNLOCK_PASSED AND created:[now-{{days}}d TO now])" }, + "sort": [], "searchAfter": [] + } + } +``` + +Everything inside this searchQuery object matches the standard format of an [IdentityNow search query](https://documentation.sailpoint.com/saas/help/search/building-query.html). A limited number of examples are provided [here](https://developer.sailpoint.com/idn/api/v3/search-post), but the searchQuery object is mapped to the full search object. This means that you can add any search query values missing from this object. diff --git a/products/idn/tools/cli/Templates/spconfig.md b/products/idn/tools/cli/Templates/spconfig.md new file mode 100644 index 000000000..9f7315f97 --- /dev/null +++ b/products/idn/tools/cli/Templates/spconfig.md @@ -0,0 +1,87 @@ +--- +id: cli-template-spconfig +title: SPConfig Template +pagination_label: CLI Templates SPConfig +sidebar_label: SPConfig +sidebar_position: 7 +sidebar_class_name: cli-template-spconfig +keywords: ['cli', 'template', 'spconfig'] +description: Learn about the CLI commands you can use to interact with VAs in this guide. +slug: /tools/cli/templates/spconfig +tags: ['CLI'] +--- + +Use SPConfig templates to perform complex import and export operations with IdentityNow configurations + +This is an example of a template file with one SPConfig templated populated + +```json +[ + { + "name": "all-objects", + "description": "Export all available objects", + "variables": [], + "exportBody": { + "description": "Export all available objects", + "excludeTypes": [], + "includeTypes": [ + "SOURCE", + "RULE", + "TRIGGER_SUBSCRIPTION", + "TRANSFORM", + "IDENTITY_PROFILE" + ], + "objectOptions": {} + } + } +] +``` + +This is the anatomy of a SPConfig template + +```json + + { + "name": "all-objects", +``` + +The search template name that displays in the template list when you run `sail spconfig template`. + +You can also provide this name as an argument: `sail spconfig template all-objects` + +```json + "description": "Export all available objects", +``` + +The spconfig template description that displays below the template name + +in the `sail spconfig template` list + +```json + "variables": [], +``` + +Use variables to dynamically populate values in the following content during command run time. + +```json + "exportBody": { +``` + +The below object matches that detailed in the [API docs](https://developer.sailpoint.com/idn/api/beta/export-sp-config) + +```json + "description": "Export all available objects", + "excludeTypes": [], + "includeTypes": [ + "SOURCE", + "RULE", + "TRIGGER_SUBSCRIPTION", + "TRANSFORM", + "IDENTITY_PROFILE" + ], + "objectOptions": {} + } + + } + +``` From de7649a6656f45ddea0d7f374e982948333550af Mon Sep 17 00:00:00 2001 From: "james.haytko" Date: Tue, 9 May 2023 12:34:59 -0500 Subject: [PATCH 2/2] Edits --- products/idn/tools/cli/Templates/report.md | 22 ++++++++++++-------- products/idn/tools/cli/Templates/search.md | 18 ++++++++++------ products/idn/tools/cli/Templates/spconfig.md | 16 +++++++------- 3 files changed, 34 insertions(+), 22 deletions(-) diff --git a/products/idn/tools/cli/Templates/report.md b/products/idn/tools/cli/Templates/report.md index df2f197f0..f3b4d8066 100644 --- a/products/idn/tools/cli/Templates/report.md +++ b/products/idn/tools/cli/Templates/report.md @@ -6,12 +6,12 @@ sidebar_label: Report sidebar_position: 7 sidebar_class_name: cli-template-report keywords: ['cli', 'template', 'report'] -description: Learn about the CLI commands you can use to interact with VAs in this guide. +description: Learn about the commands you can use to run report templates from the CLI. slug: /tools/cli/templates/report tags: ['CLI'] --- -Use Report Templates to run a set of simple predefined search queries from the CLI Reports are most useful when you do not care about the search results returned from a query, and only want to know the Count of results. +Use report templates to run sets of simple, predefined search queries from the CLI. Reports are most useful when you don't care about the search results returned from a query and you only want to know the count of results. This is an example of a report template: @@ -35,7 +35,7 @@ This is an example of a report template: ] ``` -This is the report template anatomy +This is the report template anatomy: ```json [ @@ -43,23 +43,27 @@ This is the report template anatomy "name": "provisioning-and-security", ``` -The Name of the search template. +This is the report template's name. -This is what will show up in the template list when running `sail report`. +It displays in the template list when you run `sail report`. -This is also the name you can provide as an argument `sail report provisioning-and-security` +You can also provide the name as an argument: `sail report provisioning-and-security` ```json "description": "All account unlocks in the tenant for a given time range", ``` -The description of the report template, this will show below the template name in the `sail report` list +This is the report template's description. + +It displays following the template name in the `sail report` list. ```json "variables": [{"name": "days", "prompt": "Days before today"}], ``` -Variables are used to populate values in the content below dynamically during command run time for example the Variable in this template is configured so you can choose how many days back you want to search for provisioning-and-security events when you run `sail report provisioning-and-security` a prompt appears saying `Input Days before today:` the number you enter is then populated anywhere that variable is used in the below object, and the query is run +Use variables to dynamically populate values in the following content during command run time. + +For example, the variable in this template is configured so you can choose how many days back you want to search for provisioning-and-security events. When you run `sail report provisioning-and-security`, a prompt displays, `Input Days before today:` The number you enter will then populate anywhere the variable is used in the following object, and then the query runs. ```json "queries": [ @@ -77,4 +81,4 @@ Variables are used to populate values in the content below dynamically during co ] ``` -This is a list of the queries that will be run, currently variables for days are populated +This is a list of the queries that will run. Currently, the variables for days populate. diff --git a/products/idn/tools/cli/Templates/search.md b/products/idn/tools/cli/Templates/search.md index e54a881de..d24065e3a 100644 --- a/products/idn/tools/cli/Templates/search.md +++ b/products/idn/tools/cli/Templates/search.md @@ -6,14 +6,14 @@ sidebar_label: Search sidebar_position: 7 sidebar_class_name: cli-template-search keywords: ['cli', 'template', 'search'] -description: Learn about the CLI commands you can use to interact with VAs in this guide. +description: Learn about the commands you can use to run search templates from the CLI. slug: /tools/cli/templates/search tags: ['CLI'] --- -Use Search Templates to run predefined search queries from the CLI +Use search templates to run predefined search queries from the CLI. -This is an example of a template file with 3 search templates populated +This is an example of a template file with 3 search templates populated: ```json [ @@ -72,7 +72,9 @@ This is the search template anatomy: "name": "all-account-unlocks", ``` -The search template name that displays in the template list when you run `sail search template`. +This is the search template's name. + +It displays in the template list when you run `sail search template`. You can also provide this name as an argument: `sail search template all-account-unlocks` @@ -80,13 +82,17 @@ You can also provide this name as an argument: `sail search template all-account "description": "All account unlocks in the tenant for a given time range" ``` -The search template description that displays below the template name in the `sail search template` list +This is the search template's description. + +It displays following the template name in the `sail search template` list. ```json "variables": [{"name": "days", "prompt": "Days before today"}], ``` -Use variables to dynamically populate values in the following content during command run time. For example, the variable in this template is configured such that you can choose how many days back you want to search for account unlock events. When you run `sail search template all-account-unlocks`, a prompt displays, saying `Input Days before today:` The number you enter is then populated anywhere that variable is used in the following object, and the query runs. +Use variables to dynamically populate values in the following content during command run time. + +For example, the variable in this template is configured so you can choose how many days back you want to search for account unlock events. When you run `sail search template all-account-unlocks`, a prompt displays, `Input Days before today:` The number you enter will then populate anywhere the variable is used in the following object, and then the query runs. ```json "searchQuery": { diff --git a/products/idn/tools/cli/Templates/spconfig.md b/products/idn/tools/cli/Templates/spconfig.md index 9f7315f97..886092c5c 100644 --- a/products/idn/tools/cli/Templates/spconfig.md +++ b/products/idn/tools/cli/Templates/spconfig.md @@ -6,14 +6,14 @@ sidebar_label: SPConfig sidebar_position: 7 sidebar_class_name: cli-template-spconfig keywords: ['cli', 'template', 'spconfig'] -description: Learn about the CLI commands you can use to interact with VAs in this guide. +description: Learn about the SPConfig template commands you can use to import and export configurations from the CLI. slug: /tools/cli/templates/spconfig tags: ['CLI'] --- -Use SPConfig templates to perform complex import and export operations with IdentityNow configurations +Use SPConfig templates to perform complex import and export operations with IdentityNow (IDN) configurations. -This is an example of a template file with one SPConfig templated populated +This is an example of a template file with one SPConfig template populated: ```json [ @@ -37,7 +37,7 @@ This is an example of a template file with one SPConfig templated populated ] ``` -This is the anatomy of a SPConfig template +This is the SPConfig template anatomy: ```json @@ -45,7 +45,9 @@ This is the anatomy of a SPConfig template "name": "all-objects", ``` -The search template name that displays in the template list when you run `sail spconfig template`. +This is the SPConfig template's name. + +The SPConfig template name displays in the template list when you run `sail spconfig template`. You can also provide this name as an argument: `sail spconfig template all-objects` @@ -53,7 +55,7 @@ You can also provide this name as an argument: `sail spconfig template all-objec "description": "Export all available objects", ``` -The spconfig template description that displays below the template name +This is the SPConfig template's description. in the `sail spconfig template` list @@ -67,7 +69,7 @@ Use variables to dynamically populate values in the following content during com "exportBody": { ``` -The below object matches that detailed in the [API docs](https://developer.sailpoint.com/idn/api/beta/export-sp-config) +The following object matches that detailed in the [API docs](https://developer.sailpoint.com/idn/api/beta/export-sp-config) ```json "description": "Export all available objects",