LukeParke/developer.sailpoint.com
1
0
Fork 0
mirror of https://github.com/LukeHagar/developer.sailpoint.com.git synced 2025-12-09 20:37:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor docusaurus site for Identity Security Cloud

Browse Source
This commit is contained in:
Tyler Mairose
2024-02-28 10:26:45 -05:00
parent a1ecd14e3b
commit afcc52afc5
388 changed files with 859 additions and 2666 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/tools/sdk/go/creating-resources.md Normal file
View File

@@ -0,0 +1,89 @@
---
id: go-sdk-create
title: Creating resources with the Go SDK
pagination_label: Go SDK
sidebar_label: Create a resource
sidebar_position: 2
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'create']
description: Learn how to create new resources the Golang SDK in this guide.
slug: /tools/sdk/go/create
tags: ['SDK', 'Software Development Kit']
---
Here is an example create workgroup script from the beta APIs you can copy into your "sdk.go" instance to try it out:
```go showLineNumbers
package main
import (
"context"
"encoding/json"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
"github.com/sailpoint-oss/golang-sdk/beta"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, _, err := apiClient.V3.PublicIdentitiesApi.GetPublicIdentities(ctx).Limit(1).Execute()
identity := "IDENTITY"
workgroupName := "DB Access Governance Group"
workgroupDescription := "Description of the Governance Group"
workgroup := beta.WorkgroupDto{
Name: &workgroupName,
Description: &workgroupDescription,
Owner: &beta.OwnerDto{
Id: resp[0].Id,
Name: resp[0].Name,
Type: &identity,
},
}
newWorkgroup, request, errMessage := apiClient.Beta.GovernanceGroupsApi.CreateWorkgroup(ctx).WorkgroupDto(workgroup).Execute()
if errMessage != nil {
fmt.Fprintf(os.Stderr, "Error when calling `GovernanceGroupsApi.CreateWorkgroup``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", request)
}
b, _ := json.MarshalIndent(newWorkgroup, "", " ")
fmt.Fprint(os.Stdout, string(b))
}
```
The example uses the `GetPublicIdentities` method from the `PublicIdentitiesApi` to pull an identity needed to be the owner of the Workgroup.
On lines 20-32 the new workgroup object is initialized and sent to the `CreateWorkgroup` method on line 34.
To run the code, run this command:
```go
go run sdk.go
```
The WorkGroup is assigned to the `newWorkgroup` variable and the details are printed out:
```json
{
"created": null,
"description": "Description of the Governance Group",
"modified": null,
"name": "DB Access Governance Group",
"owner": {
"displayName": "Brian Mendoza",
"emailAddress": null,
"id": "0003c25c365e492381d4e557b6159f9b",
"name": "Brian Mendoza",
"type": "IDENTITY"
}
}
```

58
docs/tools/sdk/go/deleting-resources.md Normal file
View File

@@ -0,0 +1,58 @@
---
id: go-sdk-delete
title: Delete resources with the Go SDK
pagination_label: Go SDK
sidebar_label: Delete a resource
sidebar_position: 4
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'delete']
description: Learn how to delete resources with the Golang SDK in this guide.
slug: /tools/sdk/go/delete
tags: ['SDK', 'Software Development Kit']
---
Here is an example script that searches for the Workgroup created in [Create a resource](./creating-resources.md) by name and calls the delete method to remove it from your environment.
```go
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
workgroup, r, err := apiClient.Beta.GovernanceGroupsApi.ListWorkgroups(ctx).Filters(`name eq "DB Access Governance Group"`).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when retrieving workgroup`: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
response, errorMessage := apiClient.Beta.GovernanceGroupsApi.DeleteWorkgroup(ctx, *workgroup[0].Id).Execute()
if errorMessage != nil {
fmt.Fprintf(os.Stderr, "Error when updating workgroup`: %v\n", errorMessage)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", response)
}
fmt.Fprintf(os.Stdout, "Resource Deleted: %v\n", response.StatusCode)
}
```
To run the code, run this command:
```go
go run sdk.go
```
The deletionStatus is returned by the SDK with a value of 204.

35
docs/tools/sdk/go/error-handling.md Normal file
View File

@@ -0,0 +1,35 @@
---
id: go-sdk-error-handling
title: Error handling with the Go SDK
pagination_label: Go SDK
sidebar_label: Error Handling
sidebar_position: 8
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'error']
description: Learn how to handle errors with the Golang SDK in this guide.
slug: /tools/sdk/go/error-handling
tags: ['SDK', 'Software Development Kit']
---
The SDK returns the response object, request and error object for each method. The error object will be defined for any response status that falls out of the range of 2xx.
You can use an `if` statement to check whether there are any errors with the request and take actions on the results, such as logging the message or performing additional actions before exiting the program:
```go
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Filters("This is an incorrect string").Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `TransformsApi.ListTransforms``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
```
The program will continue running unless you specify to end it. Use `os.Exit(0)` within the error check to stop execution after an error is found.
```go
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Filters("This is an incorrect string").Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `TransformsApi.ListTransforms``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
os.Exit(0)
}
```

61
docs/tools/sdk/go/getting-started.md Normal file
View File

@@ -0,0 +1,61 @@
---
id: go-sdk-getting-started
title: Getting started with the Go SDK
pagination_label: Go SDK
sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'start']
description: Learn how to use the Golang SDK in this guide.
slug: /tools/sdk/go/getting-started
tags: ['SDK', 'Software Development Kit']
---
Once your SDK is installed and configured, you can start accessing the SDK's different functionalities. This guide will walk through some examples of this functionality. To learn how to install and configure the Golang SDK, refer to [Installation and Configuration](./index.mdx).
### List Transforms
Create a file in your project called `sdk.go` with the following content:
```go
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `TransformsApi.ListTransforms``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
fmt.Fprintf(os.Stdout, "All Transforms from `TransformsApi.ListTransforms`: %v\n", resp)
}
```
To run the code, run this command:
```go
go run sdk.go
```
You can make changes to the API you are calling by changing this line:
```go
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Execute()
```
- To call a different version of the APIs, change `V3` to `Beta`, `V2`, or `CC`.
- To call a different API collection, change `TransformsApi` to another collection, like `SourcesApi`, for example.
- To call a different endpoint, change `ListTransforms` to another endpoint, like `GetTransform`, for example.

196
docs/tools/sdk/go/index.mdx Normal file
View File

@@ -0,0 +1,196 @@
---
id: go-sdk
title: Go SDK
pagination_label: Go SDK
sidebar_label: Golang
sidebar_position: 2
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk']
description: Learn how to use the Golang SDK in this guide.
slug: /tools/sdk/go
tags: ['SDK', 'Software Development Kit']
---
Read this guide to learn how to use the Go SDK. The Go SDK has some pre-built code examples you can use to learn how to build tools that can interact with IdentityNow.
## Requirements
You need the following to use the Go SDK:
- Golang version 1.18 or above. You can download it [here](https://go.dev/dl/). You can use `go version` to check your version.
- Your tenant name in IdentityNow. To learn how to find it, refer to [Getting Started](/idn/api/getting-started#find-your-tenant-name). The SDK will use this tenant name to connect to your IdentityNow instance.
- A PAT with a client secret and ID. To learn how to create one in IDN, refer to [Personal Access Tokens](https://documentation.sailpoint.com/saas/help/common/api_keys.html#generating-a-personal-access-token). The SDK will use this PAT to authenticate with the SailPoint APIs.
## Setup
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a few commands that will allow you to quickly get started with the Go SDK. To learn how to install and use the SailPoint CLI, refer to [SailPoint CLI](https://developer.sailpoint.com/idn/tools/cli#get-the-cli).
Once the CLI is installed and configured, run this command to create a new Go project with the Go SDK:
```bash
sail sdk init golang go-example
```
Running the command will create the structure for your project:
```text
|-- go-example
| |-- go.mod
| |-- go.sum
| |-- sdk.go
```
Navigate into your project folder and run this command to install the required dependencies:
```bash
go mod tidy
```
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
<details>
<summary>Manual Installation</summary>
To begin your go project, you will need to create a directory for your project.
To create a project directory, run this command:
```bash
mkdir golang-example
```
Then run this command to change into your project directory:
```bash
cd golang-example
```
To initialize your project and create the `go.mod` file, run this command in your project directory:
```go
go mod init github.com/github-repo-name/golang-example
```
You will edit this file to add the SailPoint SDK to your project.
To install the SailPoint SDK, run this command:
```go
go get github.com/sailpoint-oss/golang-sdk
```
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
## Configure
You must provide configuration to the SDK so that it can authenticate to your SailPoint tenant and make API calls. To do so, you can use a configuration file, "config.json", or environment variables.
### Configuration File
The SDK requires a configuration file to be named "config.json". Within the file, provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a command to generate the "config.json" file with your currently configured CLI credentials.
```bash
sail sdk init config
```
If you have multiple environments configured with the CLI, you can pass an additional parameter to state the environment you wish to create a "config.json" for.
To pass an additional parameter that states the environment you want to configure, run this command:
```bash
sail sdk init config --env devrel
```
#### Example "config.json"
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
<details>
<summary>Manual Configuration</summary>
Create a file named "config.json", and provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
#### Example "config.json"
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
:::warning
Please ensure this file is ignored in your version control system (ex. .gitignore for git)
:::
### Environment variable configuration
You can also store your configuration in environment variables.
To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like `~/.bash_profile`.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="linux_mac" label="Linux/Mac" default>
```bash
export SAIL_BASE_URL=https://[tenant].api.identitynow.com
export SAIL_CLIENT_ID=[clientID]
export SAIL_CLIENT_SECRET=[clientSecret]
```
</TabItem>
<TabItem value="windows" label="Windows PowerShell">
```bash
$env:SAIL_BASE_URL=https://[tenant].api.identitynow.com
$env:SAIL_CLIENT_ID=[clientID]
$env:SAIL_CLIENT_SECRET=[clientSecret]
```
To get your environment variables to persist across PowerShell sessions, run these commands instead:
```powershell
[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://[tenant].api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','[clientID]')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','[clientSecret]')
```
</TabItem>
</Tabs>
## Discuss
You can use this SDK to build new tools that extend your IDN platform and improve experiences across your organization. Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!
## Getting Started
To get started using the SDK, refer to the [Getting Started Guide](./getting-started.md).

78
docs/tools/sdk/go/pagination.md Normal file
View File

@@ -0,0 +1,78 @@
---
id: go-sdk-paginate
title: Paginate results with the Go SDK
pagination_label: Go SDK
sidebar_label: Paginate Results
sidebar_position: 5
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'paginate']
description: Learn how to paginate results with the Golang SDK in this guide.
slug: /tools/sdk/go/paginate
tags: ['SDK', 'Software Development Kit']
---
By default, your requests will return a maximum of 250 records. To return more, you must implement pagination. To learn more about pagination, refer to [Paginating Results](/idn/api/standard-collection-parameters/#paginating-results).
Pagination is implemented with the SDK in the following code block on line 18:
```go showLineNumbers
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
v3 "github.com/sailpoint-oss/golang-sdk/v3"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, r, err := sailpoint.PaginateWithDefaults[v3.Account](apiClient.V3.AccountsApi.ListAccounts(ctx))
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `PaginateWithDefaults[v3.Account]``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `PaginateWithDefaults[v3.Account]`: %v\n", resp[0].Name)
}
```
The `PaginateWithDefaults` function takes a return type, `v3.Account`, and the list method to invoke, in this case `ListAccounts` from the AccountsApi. By default, the `PaginateWithDefaults` method gets 10000 results at an increment of 250.
To change the limit and increment, you can use the available 'Paginate' function:
```go
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
v3 "github.com/sailpoint-oss/golang-sdk/v3"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
resp, r, err := sailpoint.Paginate[v3.Account](apiClient.V3.AccountsApi.ListAccounts(ctx), 0, 250, 150000)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `Paginate[v3.Account]``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `Paginate[v3.Account]`: %v\n", resp[0].Name)
}
```
You must provide the `Paginate` function with the following: the return type, `v3.Account`, the list endpoint, `ListAccounts`, the initial offset, `0`, the increment, `250`, and the limit, `150000`.

47
docs/tools/sdk/go/retries.md Normal file
View File

@@ -0,0 +1,47 @@
---
id: go-sdk-retries
title: Retries with the Go SDK
pagination_label: Go SDK
sidebar_label: Retries
sidebar_position: 7
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'retry']
description: Learn how to paginate results with the Golang SDK in this guide.
slug: /tools/sdk/go/retries
tags: ['SDK', 'Software Development Kit']
---
The SDK uses the [go-retryablehttp](https://github.com/hashicorp/go-retryablehttp) module to support retry logic.
On line 17-18 of the following example, the SDK is set to retry if there is an unexpected error up to 10 times and wait 2 seconds between each retry:
```go showLineNumbers
package main
import (
"context"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
configuration.HTTPClient.RetryMax = 10
configuration.HTTPClient.RetryWaitMax = time.Second * 2
resp, r, err := apiClient.V3.TransformsApi.ListTransforms(ctx).Filters("This is an incorrect string").Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `TransformsApi.ListTransforms``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `ListAccounts`: []Account
fmt.Fprintf(os.Stdout, "First response from `TransformsApi.ListTransforms`: %v\n", resp)
}
```

88
docs/tools/sdk/go/search.md Normal file
View File

@@ -0,0 +1,88 @@
---
id: go-sdk-search
title: Search with the Go SDK
pagination_label: Go SDK
sidebar_label: Search
sidebar_position: 5
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'search']
description: Learn how to search with the Golang SDK in this guide.
slug: /tools/sdk/go/search
tags: ['SDK', 'Software Development Kit']
---
To try using the IDN [search functionality](/idn/api/v3/search-post) along with pagination, copy this code into your "sdk.go" file, following the main code:
```go
func getSearchResults(ctx context.Context, apiClient *sailpoint.APIClient) {
search := v3.NewSearchWithDefaults()
search.Indices = append(search.Indices, "identities")
searchString := []byte(`
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"-name"
]
}
`)
search.UnmarshalJSON(searchString)
resp, r, err := sailpoint.PaginateSearchApi(ctx, apiClient, *search, 0, 10, 10000)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `PaginateSearchApi``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
// response from `search`
for i := 0; i < len(resp); i++ {
fmt.Println(resp[i]["name"])
}
}
```
To run the search, run this command: `go run sdk.go` This example lists all the identities it finds in your tenant.
There are two ways to configure the search:
1. You can edit the `searchString` JSON:
```go showLineNumbers
searchString := []byte(`
{
"indices": [
"identities"
],
"query": {
"query": "*"
},
"sort": [
"-name"
]
}
`)
```
In this example, changing the `"indices"` on line 3 from `"identities"` to `"access profiles"` makes the search return access profiles instead of identities.
2. You can edit the string at the end of this `search.Indices` line to do the same thing as a shortcut:
```go
search.Indices = append(search.Indices, "identities")
```
In this example, the `"identities"` string represents an unmarshalled JSON. Changing `append(search.Indices, "identities")` to `append(search.Indices, "access profiles")` does the same thing that editing the `searchString` JSON does.
### Paginate search results
The search example includes the syntax you can use to paginate search results. Edit this line to configure the search result pagination:
```go
resp, r, err := sailpoint.PaginateSearchApi(ctx, apiClient, *search, 0, 10, 10000)
```
The first value refers to the `initialOffset`, the starting number for the results, the second refers to the `increment`, the number of records per page, and the third refers to the `limit`, the last record that can be returned.
For example, changing the first number to `21`, the second to `20`, and the third to `40` would configure the search to return records 21 to 40 and then stop.

82
docs/tools/sdk/go/updating-resources.md Normal file
View File

@@ -0,0 +1,82 @@
---
id: go-sdk-patch
title: Updating resources with the Go SDK
pagination_label: Go SDK
sidebar_label: Update a resource
sidebar_position: 3
sidebar_class_name: gosdk
keywords: ['go', 'golang', 'sdk', 'update']
description: Learn how to update resources with the Golang SDK.
slug: /tools/sdk/go/update
tags: ['SDK', 'Software Development Kit']
---
Here is an example update WorkGroup script which will update the description for the previously created Workgroup from [Create a Resource](./creating-resources.md):
```go
package main
import (
"context"
"encoding/json"
"fmt"
"os"
sailpoint "github.com/sailpoint-oss/golang-sdk"
"github.com/sailpoint-oss/golang-sdk/beta"
)
func main() {
ctx := context.TODO()
configuration := sailpoint.NewDefaultConfiguration()
apiClient := sailpoint.NewAPIClient(configuration)
workgroup, r, err := apiClient.Beta.GovernanceGroupsApi.ListWorkgroups(ctx).Filters(`name eq "DB Access Governance Group"`).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when retrieving workgroup`: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
updatedDescription := `This is an updated description for the workgroup.`
newDescriptionValue := beta.JsonPatchOperationValue{String: &updatedDescription}
patchArray := []beta.JsonPatchOperation{{Op: "replace", Path: "/description", Value: &newDescriptionValue}}
updatedWorkgroup, request, errorMessage := apiClient.Beta.GovernanceGroupsApi.PatchWorkgroup(ctx, *workgroup[0].Id).JsonPatchOperation(patchArray).Execute()
if errorMessage != nil {
fmt.Fprintf(os.Stderr, "Error when updating workgroup`: %v\n", errorMessage)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", request)
}
b, _ := json.MarshalIndent(updatedWorkgroup, "", " ")
fmt.Fprint(os.Stdout, string(b))
}
```
To run the code, run this command:
```go
go run sdk.go
```
The updated WorkGroup will be returned by the SDK:
```json
{
"created": "2023-12-04T19:37:28Z",
"description": "This is an updated description for the workgroup.",
"modified": "2023-12-04T19:37:28Z",
"name": "DB Access Governance Group",
"owner": {
"displayName": "Brian Mendoza",
"emailAddress": null,
"id": "0003c25c365e492381d4e557b6159f9b",
"name": "Brian Mendoza",
"type": "IDENTITY"
}
}
```

23
docs/tools/sdk/index.md Normal file
View File

@@ -0,0 +1,23 @@
---
id: sdk
title: SDKs
pagination_label: SDKs
sidebar_label: SDKs
sidebar_position: 2
sidebar_class_name: sdk
keywords: ['sdk']
description: A SailPoint SDK makes it easy to access the SailPoint API and extend your IDN platform.
slug: /tools/sdk
tags: ['SDK']
---
## SDKs
A SailPoint software development kit (SDK) makes it easy to access the SailPoint APIs and extend your IDN platform.
In addition to the APIs, each SDK includes SaaS connector, IDN search, and transform functionality. Each SDK also includes prebuilt examples you can use to learn how to get started.
Try one of these SDKs to get started:
- [Go SDK](./go/index.mdx)
- [Powershell SDK](./powershell/index.mdx)
- [TypeScript SDK](./typescript/index.mdx)

91
docs/tools/sdk/powershell/creating-resources.md Normal file
View File

@@ -0,0 +1,91 @@
---
id: powershell-sdk-create
title: Creating resources with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Create a resource
sidebar_position: 2
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'create']
description: Learn how to create new resources using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/create
tags: ['SDK']
---
You can use the SDK to create new resources. These cmdlets will typically start with the `New` keyword.
To see a list of available create cmdlets, run this command:
```powershell
Get-Command -Module PSSailpoint | where-object {$_.name -like "*New-*" } | Sort-Object Name | Get-Help | Format-Table Name, Synopsis
```
The SDK returns this output (all beta endpoints are designated by the Beta prefix):
```powershell
Name Synopsis
---- --------
New-AccessProfile Create an Access Profile
New-AccessRequest Submit an Access Request
New-Account Create Account
New-AuthOrgNetworkConfig Create security network configuration.
New-BetaAccessProfile Create an Access Profile
New-BetaAccessRequest Submit an Access Request
New-BetaAccount Create Account
New-BetaCampaign Create a campaign
New-BetaCampaignTemplate Create a Campaign Template
New-BetaCommonAccess Create common access items
New-BetaConnectorRule Create Connector Rule
New-BetaCustomPasswordI… Create Custom Password Instructions
New-BetaDigitToken Generate a digit token
New-BetaDomainDkim Verify domain address via DKIM
...
```
Here is an example create workgroup script from the beta APIs you can copy into your PowerShell instance to try it out:
```powershell showLineNumbers
$Identity = Get-PublicIdentities -Limit 1
$JSON = @"
{
"owner": {
"type": "IDENTITY",
"id": "$($Identity.id)",
"name": "$($Identity.name)"
},
"name": "DB Access Governance Group",
"description": "Description of the Governance Group"
}
"@
$WorkGroup = ConvertFrom-BetaJsonToWorkgroupDto -Json $JSON
$WorkGroup = Initialize-BetaWorkgroupDto -Name "DB Access Governance Group" -Description "Description of the Governance Group" -Owner @{
"type" = "IDENTITY"
"id" = $Identity.id
"name" = $Identity.name
}
New-BetaWorkgroup -WorkgroupDto $WorkGroup
```
The example uses the `Get-PublicIdentities -Limit` cmdlet to pull an identity needed to be the owner of the Workgroup and shows two ways of creating the new WorkGroup to send with the request.
The first on lines 3-15 initializes a json string then converts the string into a WorkGroup object with `ConvertFrom-BetaJsonToWorkgroupDto`
The second on lines 17-21 initializes the WorkGroup object by passing in each property of the WorkGroup.
The WorkGroup will be returned by the SDK:
```powershell
Name Value
---- -----
description Description of the Governance Group
owner {[displayName, Brian Mendoza], [emailAddress, ], [type, IDENTITY], [id, 0003c25c365e492381d4e557b6159f9b]…}
memberCount 0
connectionCount 0
id a241d625-d948-4c41-839e-869b790837a1
name DB Access Governance Group
created
modified
```

32
docs/tools/sdk/powershell/deleting-resources.md Normal file
View File

@@ -0,0 +1,32 @@
---
id: powershell-sdk-delete
title: Deleting resources with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Delete a resource
sidebar_position: 4
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'delete']
description: Learn how to delete resources using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/delete
tags: ['SDK']
---
You can use the SDK to delete resources. These cmdlets will typically start with the `Remove` keyword.
Here is an example script that searches for the previously created Workgroup by name and calls the delete cmdlet to remove it from your environment.
```powershell
$WorkGroup = Get-BetaWorkgroups -Filters 'name eq "DB Access Governance Group"'
Remove-BetaWorkgroup -Id $WorkGroup.id -WithHttpInfo
```
Using the [WithHttpInfo Switch](./getting-started.md#withhttpinfo-switch) in the script above, we can verify the operation completed successfully by the 204 status code.
```powershell
Name Value
---- -----
Response
StatusCode 204
Headers {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Vary, System.String[]]…}
```

45
docs/tools/sdk/powershell/error-handling.md Normal file
View File

@@ -0,0 +1,45 @@
---
id: powershell-sdk-error-handling
title: Error Handling with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Error Handling
sidebar_position: 7
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'error']
description: Learn how to delete resources using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/error-handling
tags: ['SDK']
---
The SDK uses the Invoke-WebRequest cmdlet to handle HTTP requests. Invoke-WebRequest will throw a terminating error for any response that falls out of the range of 2xx. A non-2xx response will immediately halt the program and produce a stack trace.
You can use a `try/catch` function to intercept any non success response and take actions on the results, such as logging the message or performing additional actions before exiting the program:
```powershell
# Catch any non 2xx response and log the status code and error message
try {
Get-Transforms -Filters "id eq"
}
catch {
Write-Host $_.Exception.Response.StatusCode.value__
Write-Host $_.ErrorDetails
}
```
The `catch` block will handle the error, and the script execution will continue. If you want to stop the scripts execution, include an `Exit` in the `catch` block:
This code ensures that the `Get-AccessProfiles` cmdlet will never be called:
```powershell
# Catch any non 2xx response and log the status code and error message. Stop the script with the Exit keyword.
try {
Get-Transforms -Filters "id eq"
}
catch {
Write-Host $_.Exception.Response.StatusCode.value__
Write-Host $_.ErrorDetails
Exit
}
Get-AccessProfiles
```

135
docs/tools/sdk/powershell/getting-started.md Normal file
View File

@@ -0,0 +1,135 @@
---
id: powershell-sdk-getting-started
title: Getting started with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'start']
description: Learn how to use the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/getting-started
tags: ['SDK']
---
Once your SDK is installed and configured, you can start accessing the SDK's different functionalities. To learn how to install and configure the PowerShell SDK, refer to [Installation and Configuration](./index.mdx).
To get an idea of what cmdlets the SDK offers run the following command. This command lists all available Get cmdlets within the SDK:
```powershell
Get-Command -Module PSSailpoint | where-object {$_.name -like "*Get-*" } | Sort-Object Name | Get-Help | Format-Table Name, Synopsis
```
The SDK returns this output:
```powershell
Name Synopsis
---- --------
Get-AccessProfile Get an Access Profile
Get-AccessProfileEntitlements List Access Profile's Entitlements
Get-AccessProfiles List Access Profiles
Get-AccessRequestApprovalSummary Get the number of access-requests-approvals
Get-AccessRequestConfig Get Access Request Configuration
Get-AccessRequestStatus Access Request Status
Get-Account Account Details
Get-AccountActivities List Account Activities
Get-AccountActivity Get an Account Activity
Get-AccountEntitlements Account Entitlements
Get-Accounts Accounts List
Get-AccountsSchema Downloads source accounts schema template
Get-ActiveCampaigns List Campaigns
...
```
## List Transforms
Let's say that you wanted to see all the transforms available in your tenant. You can search for the cmdlet:
```powershell
Get-Command -Module PSSailpoint | where-object {$_.name -like "Get-*Transform*" } | Sort-Object Name | Get-Help | Format-Table Name, Synopsis
```
The SDK returns this output (all beta endpoints are designated by the Beta prefix):
```powershell
Name Synopsis
---- --------
Get-BetaTransform Transform by ID
Get-BetaTransforms List transforms
Get-Transform Transform by ID
Get-Transforms List transforms
```
To get syntax, description and parameters for a single cmdlet, run this command:
```powershell
Get-Help Get-Transforms -Detailed
```
<details>
<summary>Cmdlet Response</summary>
```text
NAME
Get-Transforms
SYNOPSIS
List transforms
SYNTAX
Get-Transforms [[-Offset] <Nullable`1>] [[-Limit] <Nullable`1>] [[-Count] <Nullable`1>] [[-Name] <String>] [[-Filters] <String>] [-WithHttpInfo] [<CommonParameters>]
DESCRIPTION
Gets a list of all saved transform objects. A token with 'transforms-list read' authority is required to call this API.
PARAMETERS
-Offset <Nullable`1>
Offset into the full result set. Usually specified with *limit* to paginate through the results. For more information, refer to [V3 API Standard Collection
Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters).
-Limit <Nullable`1>
Max number of results to return. For more information, refer to [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters).
-Count <Nullable`1>
If *true* it will populate the *X-Total-Count* response header with the number of results that would be returned if *limit* and *offset* were ignored. Since requesting a total count can have a
performance impact, it is recommended not to send **count=true** if that value will not be used. For more information, refer to [V3 API Standard Collection
Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters).
-Name <String>
Name of the transform to retrieve from the list.
-Filters <String>
Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results). Filtering is
supported for the following fields and operators: **internal**: *eq* **name**: *eq, sw*
-WithHttpInfo [<SwitchParameter>]
A switch that, when enabled, will return a hash table of Response, StatusCode and Headers, instead of just the Response.
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, refer to
about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
```
</details>
Running `Get-Transforms` will return a list of all transforms in your tenant.
Running `Get-Transforms -Limit 10 -Filter 'name sw Test"'` will return a list of no more than 10 transforms whose names start with `Test`.
## WithHttpInfo Switch
By default, the cmdlets return just the response from the API without including any information about status code or headers returned. Use the `-WithHttpInfo` switch to return this information with the response.
```powershell
Get-Transforms -WithHttpInfo
Name Value
---- -----
Headers {[Date, System.String[]], [Transfer-Encoding, System.String[]], [Connection, System.String[]], [Server, System.String[]]…}
StatusCode 200
Response {System.Management.Automation.OrderedHashtable, System.Management.Automation.OrderedHashtable, System.Management.Automation.Ordered…
```

200
docs/tools/sdk/powershell/index.mdx Normal file
View File

@@ -0,0 +1,200 @@
---
id: powershell-sdk
title: PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: PowerShell
sidebar_position: 3
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk']
description: Learn how to use the PowerShell SDK in this guide.
slug: /tools/sdk/powershell
tags: ['SDK']
---
Read this guide to learn how to use the PowerShell SDK. The PowerShell SDK has some pre-built code examples you can use to learn how to build tools that can interact with IdentityNow.
## Requirements
You need the following to use the PowerShell SDK:
- PowerShell 6.2 or greater. To learn how to install, refer to [Installing PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.4).
- Your tenant name in IdentityNow. To learn how to find it, refer to [Getting Started](/idn/api/getting-started#find-your-tenant-name). The SDK will use this tenant name to connect to your IdentityNow instance.
- A PAT with a client secret and ID. To learn how to create one in IDN, refer to [Personal Access Tokens](https://documentation.sailpoint.com/saas/help/common/api_keys.html#generating-a-personal-access-token). The SDK will use this PAT to authenticate with the SailPoint APIs.
## Setup
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a few commands that will allow you to quickly get started with the PowerShell SDK. To learn how to install and use the SailPoint CLI, refer to [SailPoint CLI](https://developer.sailpoint.com/idn/tools/cli#get-the-cli).
Once the CLI is installed and configured, run this command to create a new PowerShell project with the PowerShell SDK:
```bash
sail sdk init powershell
```
Running the command create the structure for your project:
```text
|-- powershell-template
| |-- paginate.ps1
| |-- paginateAccounts.ps1
| |-- patchEntitlement.ps1
| |-- sdk.ps1
| |-- search.ps1
| |-- transform.ps1
```
Run this command to install the required dependencies:
```powershell
Install-Module -Name PSSailpoint
```
The command installs the SailPoint PowerShell SDK module. You will be prompted to confirm that you want to install the module from 'PSGallery'. Enter "A" to say "Yes to All".
If you already have a version of the PowerShell SDK installed, you can install a new version side-by-side with it by adding the `-Force` parameter to the end of your `Install-Module` commmand:
```powershell
Install-Module -Name PSSailpoint -Force
```
To validate that the module is installed, run this command, `Get-Module -ListAvailable PSSailpoint`, and verify that the module is listed. Additionally, you can run this command, `Get-Command -Module PSSailpoint`, to see the available commands included in the module.
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
<details>
<summary>Manual Installation</summary>
### Manually install the SDK
If access to the PowerShell Gallery isn't available, you can also install the PowerShell SDK manually.
:::caution
If you manually install the module on a machine without access to the PowerShell Gallery, you will also need to manually install updates to the SDK.
:::
Follow these steps to manually install the PowerShell module:
1. Download the source code zip from the most recent release on [GitHub](https://github.com/sailpoint-oss/powershell-sdk/releases).
2. Open the ZIP file, then open then folder labeled `powershell-sdk-x.x.x`, with the `x.x.x` representing the version you downloaded.
3. Extract the `PSSailpoint` module folder inside to one of the following locations:
- To install for the Current user: `C:\Users\<username>\Documents\WindowsPowerShell\Modules\PSSailpoint`
- To install for All users (requires Administrator privileges): `C:\Program Files\WindowsPowerShell\Modules\PSSailpoint`
4. Run `Import-Module PSSailpoint` to import the module into the current session.
5. To validate that the module is installed, run `Get-Module -ListAvailable PSSailpoint` and verify that the module is listed. Additionally, you can run `Get-Command -Module PSSailpoint` to see the module's available commands.
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
## Configure
You must provide configuration to the SDK so that it can authenticate to your SailPoint tenant and make API calls. To do so, you can use a configuration file, `config.json`, or environment variables.
### Configuration File
The SDK requires a configuration file to be named "config.json". Within the file, provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a command to generate the config.json file with your currently configured CLI credentials.
```bash
sail sdk init config
```
If you have multiple environments configured with the CLI, you can pass an additional parameter to state the environment you wish to create a `config.json` for.
To pass an additional parameter that states the environment you want to configure, run this command:
```bash
sail sdk init config --env devrel
```
#### Example `config.json`
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
<details>
<summary>Manual Configuration</summary>
Create a file named "config.json", and provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
#### Example `config.json`
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
:::warning
Please ensure this file is ignored in your version control system (ex. .gitignore for git)
:::
### Environment variable configuration
You can also store your configuration in environment variables.
To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like `~/.bash_profile`.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="linux_mac" label="Linux/Mac" default>
```bash
export SAIL_BASE_URL=https://[tenant].api.identitynow.com
export SAIL_CLIENT_ID=[clientID]
export SAIL_CLIENT_SECRET=[clientSecret]
```
</TabItem>
<TabItem value="windows" label="Windows PowerShell">
```bash
$env:SAIL_BASE_URL=https://[tenant].api.identitynow.com
$env:SAIL_CLIENT_ID=[clientID]
$env:SAIL_CLIENT_SECRET=[clientSecret]
```
To get your environment variables to persist across PowerShell sessions, run these commands instead:
```powershell
[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://[tenant].api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','[clientID]')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','[clientSecret]')
```
</TabItem>
</Tabs>
## Discuss
You can use this SDK to build new tools that extend your IDN platform and improve experiences across your organization. Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!
## Getting Started
To get started using the SDK, refer to the [Getting Started Guide](./getting-started.md).

48
docs/tools/sdk/powershell/pagination.md Normal file
View File

@@ -0,0 +1,48 @@
---
id: powershell-sdk-pagination
title: Paginate results with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Paginate Results
sidebar_position: 5
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'paginate']
description: Learn how to paginate results using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/paginate
tags: ['SDK']
---
By default, your requests will return a maximum of 250 records. To return more, you must implement pagination. To learn more about pagination, refer to [Paginating Results](/idn/api/standard-collection-parameters/#paginating-results).
Pagination is implemented with the SDK in the following code block on line 8:
```powershell showLineNumbers
$Parameters = @{
"Filters" = 'name co "Andrew"'
}
# Accounts List
try {
Invoke-Paginate -Function "Get-Accounts" -Increment 250 -Limit 1000 -InitialOffset 0 -Parameters $Parameters
} catch {
Write-Host $_
Write-Host ("Exception occurred when calling {1}: {0}" -f ($_.ErrorDetails | ConvertFrom-Json), "Get-Accounts")
Write-Host ("Response headers: {0}" -f ($_.Exception.Response.Headers | ConvertTo-Json))
}
```
The `Invoke-Paginate` cmdlet takes a few paramters. The first is the cmdlet you wish to call.
The `-Function` specifies the name of the cmdlet you wish to call. This only works on list endpoints.
The `-Increment` specifies the number of results returned in each call to the endpoint. Defaults to 250.
The `-Limit` specifies the total number of results you can return, 1000.
The `-Parameters` specifies a hashtable of additional values passed to the API endpoint. You would use this for `filters`, `sorters`, and any other query parameters.
You can also provide an `-InitialOffset` value to specify the record number to start the request on. For example, you can provide add `-InitialOffset 10` to start getting accounts from 11 instead of 0.
To find out whether an endpoint supports pagination, refer to its documentation. Any API supporting pagination lists the optional query parameters detailed in [Paginating Results](/idn/api/standard-collection-parameters/#paginating-results).

24
docs/tools/sdk/powershell/retries.md Normal file
View File

@@ -0,0 +1,24 @@
---
id: powershell-sdk-retries
title: Retries with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Retries
sidebar_position: 6
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'retry']
description: Learn how to configure retries using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/retries
tags: ['SDK']
---
The SDK supports retry logic in the case of an unexpected error. You have these two retry configuration options:
* MaximumRetryCount - How many times to retry the request. Default is 10 retries.
* RetryIntervalSeconds - How many seconds to wait between retries. Default is 5 seconds.
The following code will tell the SDK to retry 2 times after an unexpected error and wait 3 seconds between retries.
```powershell
Set-DefaultConfiguration -MaximumRetryCount 2 -RetryIntervalSeconds 3
```

88
docs/tools/sdk/powershell/search.md Normal file
View File

@@ -0,0 +1,88 @@
---
id: powershell-sdk-search
title: Search with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Search
sidebar_position: 5
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'search']
description: Learn how to search using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/search
tags: ['SDK']
---
The PowerShell SDK provides you access to IdentityNow's [Search](https://documentation.sailpoint.com/saas/help/search/index.html) functionality.
Here is an example search you can copy into your PowerShell instance to try it out:
```powershell
$Json = @"
{
"indices": [
"identities"
],
"query": {
"query": "\"john.doe\"",
"fields": [
"name"
]
}
}
"@
$Search = ConvertFrom-JsonToSearch -Json $Json
try {
Search-Post -Search $Search
} catch {
Write-Host ("Exception occurred when calling Search-Post: {0}" -f ($_.ErrorDetails | ConvertFrom-Json))
Write-Host ("Response headers: {0}" -f ($_.Exception.Response.Headers | ConvertTo-Json))
}
```
This example request uses the [Perform Search endpoint](/idn/api/v3/search-post) to search your tenant for identities with the name "john.doe".
### Paginate search results
You can paginate your search results to get records past the default limit of 10000. With pagination, you can get as many records as you want.
Use the syntax shown in this example to paginate your search results:
```powershell
$JSON = @"
{
"indices": [
"identities"
],
"query": {
"query": "*",
"fields": [
"name"
]
},
"sort": [
"-displayName"
]
}
"@
$Search = ConvertFrom-JsonToSearch -Json $JSON
try {
Invoke-PaginateSearch -Increment 5000 -Limit 150000 -Search $Search
} catch {
Write-Host $_
Write-Host ("Exception occurred when calling {1}: {0}" -f ($_.ErrorDetails | ConvertFrom-Json), "Paginate-Search")
Write-Host ("Response headers: {0}" -f ($_.Exception.Response.Headers | ConvertTo-Json))
}
```
This example searches your IdentityNow tenant for all identities and sorts them by their `displayName` in descending order. The search returns a maximum of 150000 records (the `Limit`) and 5000 records per page (the `Increment`).
To paginate the search results, you can specify these parameters:
- `-Increment`: The number of records to return per page.
- `-Limit`: The maximum number of records to return per request. The default is 10000.
- `-Offset`: The number of the first record to return with the request. The default is 0.

74
docs/tools/sdk/powershell/updating-resources.md Normal file
View File

@@ -0,0 +1,74 @@
---
id: powershell-sdk-patch
title: Updating resources with the PowerShell SDK
pagination_label: PowerShell SDK
sidebar_label: Update a resource
sidebar_position: 3
sidebar_class_name: powershellsdk
keywords: ['powershell', 'sdk', 'update']
description: Learn how to update resources using the PowerShell SDK in this guide.
slug: /tools/sdk/powershell/update
tags: ['SDK']
---
You can use the SDK to update resources. These cmdlets will typically start with the `Update` keyword.
To see a list of available create cmdlets, run this command:
```powershell
Get-Command -Module PSSailpoint | where-object {$_.name -like "*Update-*" } | Sort-Object Name | Get-Help | Format-Table Name, Synopsis
```
The SDK returns this output (all beta endpoints are designated by the Beta prefix):
```powershell
Name Synopsis
---- --------
Update-AccessProfile Patch a specified Access Profile
Update-Account Update Account
Update-AuthOrgNetworkConfig Update security network configuration.
Update-AuthUser Auth User Update
Update-BetaAccessProfile Patch a specified Access Profile
Update-BetaAccount Update Account
Update-BetaCampaign Update a Campaign
Update-BetaCampaignTemplate Update a Campaign Template
Update-BetaCommonAccessSta… Bulk update common access status
Update-BetaConnectorRule Update a Connector Rule
Update-BetaEntitlement Patch an entitlement
Update-BetaEntitlementsInB… Bulk update an entitlement list
Update-BetaEntitlementsPot… Edit entitlements for a potential rol…
Update-BetaFormDefinition Patch a form definition.
Update-BetaFormInstance Patch a form instance.
Update-BetaIdentityProfile Update the Identity Profile
Update-BetaLifecycleStates Update Lifecycle State
...
```
Here is an example update WorkGroup script which will update the description for the previously created Workgroup from [Create a Resource](./creating-resources.md):
```powershell
$WorkGroup = Get-BetaWorkgroups -Filters 'name eq "DB Access Governance Group"'
$WorkGroupUpdate = [PSCustomObject]@{
op = "replace"
path = "/description"
value = "This is an updated description for the workgroup."
}
Update-BetaWorkgroup -Id $WorkGroup.id -JsonPatchOperation $WorkGroupUpdate
```
The updated WorkGroup will be returned by the SDK:
```powershell
Name Value
---- -----
description This is an updated description for the workgroup.
owner {[displayName, Brian Mendoza], [emailAddress, ], [type, IDENTITY], [id, 0003c25c365e492381d4e557b6159f9b]…}
memberCount 0
connectionCount 0
id a241d625-d948-4c41-839e-869b790837a1
name DB Access Governance Group
created 12/1/2023 5:39:23 PM
modified 12/1/2023 5:39:23 PM
```

77
docs/tools/sdk/typescript/creating-resources.md Normal file
View File

@@ -0,0 +1,77 @@
---
id: typescript-sdk-create
title: Creating resources with The TypeScript SDK
pagination_label: Create a resource
sidebar_label: Create a resource
sidebar_position: 2
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'create']
description: Learn how to use the TypeScript SDK to create new resources.
slug: /tools/sdk/typescript/create
tags: ['SDK']
---
You can use the SDK to create new resources.
Here is an example create workgroup script from the beta APIs you can copy into your typescript project to try it out:
```typescript showLineNumbers
import {Configuration, GovernanceGroupsBetaApi, GovernanceGroupsBetaApiCreateWorkgroupRequest, PublicIdentitiesApi} from "sailpoint-api-client"
const createWorkGroup = async () => {
let apiConfig = new Configuration()
let identitiesApi = new PublicIdentitiesApi(apiConfig)
let identity = (await identitiesApi.getPublicIdentities({limit: 1})).data[0]
let api = new GovernanceGroupsBetaApi(apiConfig)
let workgroup: GovernanceGroupsBetaApiCreateWorkgroupRequest = {
workgroupDtoBeta: {
name: "DB Access Governance Group",
description: "Description of the Governance Group",
owner: {
id: identity.id,
type: "IDENTITY",
name: identity.name
}
}
}
let val = await api.createWorkgroup(workgroup)
console.log(val.data)
}
createWorkGroup()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```
The example uses the `getPublicIdentities` method from the `PublicIdentitiesApi` to pull an identity needed to be the owner of the Workgroup.
The create workgroup request is initialized on lines 10-20 using the identity's name and id in the owner object.
The WorkGroup will be returned by the SDK:
```typescript
{
description: 'Description of the Governance Group',
owner: {
displayName: 'Brian Mendoza',
emailAddress: null,
type: 'IDENTITY',
id: '0003c25c365e492381d4e557b6159f9b',
name: 'Brian Mendoza'
},
memberCount: 0,
connectionCount: 0,
id: '541ded73-d4b4-41d6-a10c-8085c02815bb',
name: 'DB Access Governance Group',
created: null,
modified: null
}
```

44
docs/tools/sdk/typescript/deleting-resources.md Normal file
View File

@@ -0,0 +1,44 @@
---
id: typescript-sdk-delete
title: Deleting resources with The TypeScript SDK
pagination_label: Delete a resource
sidebar_label: Delete a resource
sidebar_position: 4
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'delete']
description: Learn how to use the TypeScript SDK to delete resources.
slug: /tools/sdk/typescript/delete
tags: ['SDK']
---
You can use the SDK to delete resources.
Here is an example script that searches for the Workgroup created in [Create a resource](./creating-resources.md) by name and calls the delete method to remove it from your environment.
```typescript
import {Configuration, GovernanceGroupsBetaApi, GovernanceGroupsBetaApiCreateWorkgroupRequest, GovernanceGroupsBetaApiPatchWorkgroupRequest, PublicIdentitiesApi} from "sailpoint-api-client"
const deleteWorkgroup = async () => {
let apiConfig = new Configuration()
let api = new GovernanceGroupsBetaApi(apiConfig)
let workgroup = (await api.listWorkgroups({filters: 'name eq "DB Access Governance Group"'})).data[0]
if (workgroup.id !== undefined) {
let deletionStatus = (await api.deleteWorkgroup({id: workgroup.id})).status
console.log(deletionStatus)
} else {
console.log("Workgroup was not found, id is missing for delete request.")
}
}
deleteWorkgroup()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```
The deletionStatus is returned by the SDK with a value of 204.

46
docs/tools/sdk/typescript/error-handling.md Normal file
View File

@@ -0,0 +1,46 @@
---
id: typescript-sdk-error-handling
title: Error Handling with The TypeScript SDK
pagination_label: Error Handling
sidebar_label: Error Handling
sidebar_position: 8
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'error']
description: Learn how to configure error handling when using the TypeScript SDK.
slug: /tools/sdk/typescript/error-handling
tags: ['SDK']
---
The TypeScript SDK uses the Axios library to handle HTTP requests. Axios will throw an error for any response status that falls outside the range of 2xx. A non-2xx response will immediately halt the program and produce a stack trace. Axios provides two methods for gracefully handling error responses from an API.
The first method is to use a `catch` function to intercept any unsuccessful response and take actions on the results, such as logging the message or performing additional actions before exiting the program:
```typescript showLineNumbers
// Catch any non 2xx response and log the error message and metadata
let transforms = await api.listTransforms().catch(function (error) {
console.log(error.response.data);
console.log(error.response.status);
console.log(error.response.headers);
})
```
The second method is to define which HTTP status codes should throw an error for a given request using the `validateStatus` option. This gives you an opportunity to recover from a bad request without exiting the program.
If you don't want the program to exit for 4xx response codes, you can use this configuration:
```typescript showLineNumbers
// Resolve only if the status code is less than 500
let transforms = await api.listTransforms({filters: 'id eq'}, {validateStatus: function (status) { return status < 500 }})
if (transforms.status === 200) {
console.log(transforms)
} else if (transforms.status === 400 ) {
console.log("The filter is invalid. Continuing execution.")
}
```
If you don't want the program to exit for any error response, you can use this configuration:
```typescript
await api.listTransforms({}, {validateStatus: function (status) { return true }})
```

69
docs/tools/sdk/typescript/getting-started.md Normal file
View File

@@ -0,0 +1,69 @@
---
id: typescript-sdk-getting-started
title: Getting Started with The TypeScript SDK
pagination_label: Getting Started
sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'start']
description: Learn how to use the TypeScript SDK in this guide.
slug: /tools/sdk/typescript/getting-started
tags: ['SDK']
---
Once your SDK is installed and configured, you can start accessing the SDK's different functionalities. To learn how to install and configure the Typescript SDK, refer to [Installation and Configuration](./index.mdx).
This guide will walk through some examples of this functionality.
To make sure that your SDK is connecting to the APIs you need, you can specify the API within the curly brackets in `import {}` at the top of the "index.ts" file. In this example, you could add `Configuration` and `TransformsApi` to add the functionality to list transforms.
### List Transforms in your tenant
```typescript
import {Configuration, TransformsApi} from "sailpoint-api-client"
const getTransforms = async() => {
// Initialize configuration, this requests a token using your configured credentials
// to be able to call out to APIs
let apiConfig = new Configuration()
// Initialize the TransformsApi, this creates an instance of the TransformsApi.
// The configuration object is passed in so that the API can add your token to the request
let api = new TransformsApi(apiConfig)
// Call out to your tenant to get the list of transforms.
let transforms = await api.listTransforms()
console.log(transforms)
}
getTransforms()
```
To compile the file, first run the `tsc src/index.ts` command. This command creates a corresponding `index.js` file you can use to run the SDK.
To run the SDK, run the `node src/index.js` command. This command sends the request and outputs a list of transforms stored in your tenant.
### Use query parameters to filter your tenant's transform list
Using the same SDK function, you can list your transforms but limit the results to only what you want. This example wants a list of no more than 10 transforms that start with the name "Test":
Refer to [List Transforms](https://developer.sailpoint.com/idn/api/v3/list-transforms) for all its supported query parameters.
```typescript
import {Configuration, TransformsApi} from "sailpoint-api-client"
const getTransforms = async() => {
let apiConfig = new Configuration()
let api = new TransformsApi(apiConfig)
let transforms = await api.listTransforms({limit: 10, filters: 'name sw "Test"'})
console.log(transforms)
}
getTransforms()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```

236
docs/tools/sdk/typescript/index.mdx Normal file
View File

@@ -0,0 +1,236 @@
---
id: typescript-sdk
title: TypeScript SDK
pagination_label: TypeScript SDK
sidebar_label: TypeScript
sidebar_position: 4
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk']
description: Learn how to use the TypeScript SDK in this guide.
slug: /tools/sdk/typescript
tags: ['SDK']
---
## Overview
Learn how to install and configure the TypeScript SDK in this guide.
## Requirements
You need the following to use the TypeScript SDK:
- **Node**. To learn how to download it and set it up, go [here](https://nodejs.org/en/download).
- **TypeScript**. You can use `npm` to install TypeScript globally. This means that you can use the `tsc` command anywhere in your terminal. To do so, run this command:
```bash
npm install -g typescript
```
- Your tenant name in IDN. To learn how to find it, refer to [Getting Started](/idn/api/getting-started#find-your-tenant-name). The SDK will use this tenant name to connect to your IDN instance.
- A PAT with a client secret and ID. To learn how to create one in IDN, refer to [Personal Access Tokens](https://documentation.sailpoint.com/saas/help/common/api_keys.html#generating-a-personal-access-token). The SDK will use this PAT to authenticate with the SailPoint APIs.
## Setup
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a few commands that will allow you to quickly get started with the Typescript SDK. To learn how to install and use the SailPoint CLI, refer to [SailPoint CLI](https://developer.sailpoint.com/idn/tools/cli#get-the-cli).
Once the CLI is installed and configured, run this command to create a new Typescript project with the Typescript SDK:
```bash
sail sdk init typescript typescript-example
```
Running the command creates the structure for your project:
```text
|-- typescript-example
| |-- package.json
| |-- src
| | |-- index.ts
| |-- tsconfig.json
```
Navigate into your project folder and run this command to install the required dependencies:
```bash
npm install
```
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
<details>
<summary>Manual Installation</summary>
To begin your typescript project, you will need to create a directory for your project. Run this command to create your project directory:
```bash
mkdir typescript-example
```
Then run this command to change into your project directory:
```bash
cd typescript-example
```
To initialize your project directory and create the "package.json" file, run this command in your project directory.
```bash
npm init
```
You will update this file with the dependencies necessary to use the SDK.
Create a source folder named "src". The SDK will include the "src/**/*" folder path when it compiles, so your SDK file must be there. Run this command to create the "src" folder:
```bash
mkdir src
```
Go to the `src` folder and create a file named "index.ts". You will need to compile the "index.ts" file to run the SDK. You can leave this "index.ts" file empty for now.
Go to the project directory and create a file named "tsconfig.json". This file will contain your compiler configuration. Copy this information into your "tsconfig.json" file:
```typescript
{
"compilerOptions": {
"target": "ES2020", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
"module": "commonjs", /* Specify what module code is generated. */
"moduleResolution": "node", /* Specify how TypeScript looks up a file from a given module specifier. */
"esModuleInterop": true, /* Omit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
"strict": true, /* Enable all strict type-checking options. */
"skipLibCheck": true,
"outDir": "./build",
"rootDir": "src",
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
Run this command to add the SailPoint SDK to your project's dependencies:
```bash
npm install sailpoint-api-client
```
Or run this command to do the same:
```bash
yarn add sailpoint-api-client
```
The SDK is now installed. To learn how to configure the SDK, refer to the [Configure section](#configure).
</details>
## Configure
You must provide configuration to the SDK so that it can authenticate to your SailPoint tenant and make API calls. To do so, you can use a configuration file, "config.json", or environment variables.
### Configuration File
The SDK requires a configuration file to be named "config.json". Within the file, provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
<details>
<summary>CLI Assisted <em>(Recommended)</em></summary>
The SailPoint CLI offers a command to generate the config.json file with your currently configured CLI credentials.
```bash
sail sdk init config
```
If you have multiple environments configured with the CLI, you can pass an additional parameter to state the environment you wish to create a "config.json" for.
To pass an additional parameter that states the environment you want to configure, run this command:
```bash
sail sdk init config --env devrel
```
#### Example "config.json"
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
<details>
<summary>Manual Configuration</summary>
Create a file named "config.json", and provide these key/value pairs: `ClientID`, `ClientSecret`, `BaseUrl`.
#### Example "config.json"
```json
{
"ClientID": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseUrl": "https://[tenant].api.identitynow.com"
}
```
</details>
:::warning
Please ensure this file is ignored in your version control system (ex. .gitignore for git)
:::
### Environment variable configuration
You can also store your configuration in environment variables.
To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like `~/.bash_profile`.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="linux_mac" label="Linux/Mac" default>
```bash
export SAIL_BASE_URL=https://[tenant].api.identitynow.com
export SAIL_CLIENT_ID=[clientID]
export SAIL_CLIENT_SECRET=[clientSecret]
```
</TabItem>
<TabItem value="windows" label="Windows PowerShell">
```bash
$env:SAIL_BASE_URL=https://[tenant].api.identitynow.com
$env:SAIL_CLIENT_ID=[clientID]
$env:SAIL_CLIENT_SECRET=[clientSecret]
```
To get your environment variables to persist across PowerShell sessions, run these commands instead:
```powershell
[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://[tenant].api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','[clientID]')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','[clientSecret]')
```
</TabItem>
</Tabs>
## Discuss
You can use this SDK to build new tools that extend your IDN platform and improve experiences across your organization. Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!
## Getting Started
To get started using the SDK, refer to the [Getting Started Guide](./getting-started.md).

45
docs/tools/sdk/typescript/pagination.md Normal file
View File

@@ -0,0 +1,45 @@
---
id: typescript-sdk-pagination
title: Paginate Results with The TypeScript SDK
pagination_label: Paginate Results
sidebar_label: Paginate Results
sidebar_position: 5
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'paginate']
description: Learn how to use the TypeScript SDK to paginate results.
slug: /tools/sdk/typescript/paginate
tags: ['SDK']
---
By default, your requests will return a maximum of 250 records. To return more, you must implement pagination. To learn more about pagination, refer to [Paginating Results](/idn/api/standard-collection-parameters/#paginating-results).
Pagination is implemented with the SDK in the following code block on line 7:
```typescript showLineNumbers
import {Configuration, AccountsApi, Paginator} from "sailpoint-api-client"
const getPaginatedAccounts = async () => {
let apiConfig = new Configuration()
let api = new AccountsApi(apiConfig)
const val = await Paginator.paginate(api, api.listAccounts, {limit: 1000}, 250)
console.log(val)
}
getPaginatedAccounts()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```
The function takes a few parameters: the first is the API instance that you wish to call, created on line 5. The next parameter is the function in which you want to invoke the pagination against. The earlier example wants to list accounts, so it calls `api.listAccounts`.
The `limit` specifies the total number of results you can return, 1000. The following unlabeled number, 250, refers to the `increment`, the number of records per page. For example, changing the `limit` to 50 and the following "250" to 5 would change the request to return a total of 50 records, 5 at a time.
You can also provide an `offset` value to specify the record number to start the request on. For example, you can add `{offset: 11}` to start getting accounts from 11 instead of 0.
To find out whether an endpoint supports pagination, refer to its documentation. Any API supporting pagination lists the optional query parameters detailed in [Paginating Results](/idn/api/standard-collection-parameters/#paginating-results).

45
docs/tools/sdk/typescript/retries.md Normal file
View File

@@ -0,0 +1,45 @@
---
id: typescript-sdk-retries
title: Retries with The TypeScript SDK
pagination_label: Retries
sidebar_label: Retries
sidebar_position: 7
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'retry']
description: Learn how to configure retries when using the TypeScript SDK.
slug: /tools/sdk/typescript/retries
tags: ['SDK']
---
The SDK supports retry logic in the case of an unexpected error. You are able to configure the number of retries and the delay between retries. This logic is implemented in lines 7-12:
```typescript showLineNumbers
import {Configuration, axiosRetry, AccountsApi, Paginator} from "sailpoint-api-client"
const getPaginatedAccounts = async () => {
let apiConfig = new Configuration()
apiConfig.retriesConfig = {
retries: 4,
retryDelay: axiosRetry.exponentialDelay,
onRetry(retryCount, error, requestConfig) {
console.log(`retrying due to request error, try number ${retryCount}`)
},
}
let api = new AccountsApi(apiConfig)
const val = await Paginator.paginate(api, api.listAccounts, {limit: 100}, 10)
console.log(val)
}
getPaginatedAccounts()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```

49
docs/tools/sdk/typescript/search.md Normal file
View File

@@ -0,0 +1,49 @@
---
id: typescript-sdk-search
title: Search with The TypeScript SDK
pagination_label: Search
sidebar_label: Search
sidebar_position: 6
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'search']
description: Learn how to use the TypeScript SDK to search.
slug: /tools/sdk/typescript/search
tags: ['SDK']
---
To try using the IDN [search functionality](/idn/api/v3/search-post) along with pagination, copy this code into your "index.ts" file:
```typescript
const search = async () => {
let apiConfig = new Configuration()
let api = new SearchApi(apiConfig)
let search: Search = {
indices: [
"identities"
],
query: {
query: "*"
},
sort: ["-name"]
}
const val = await Paginator.paginateSearchApi(api, search, 100, 1000)
for (const result of val.data) {
const castedResult: IdentityDocument = result
console.log(castedResult.name)
}
}
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```
This example returns 1000 identities, 100 at a time, and sorts them in descending order by name. You can also change the search pagination by changing "100" and "1000", respectively.
The two main ways you can manipulate this example are to change the `indices` or the `query`. For example, if you add `"access profiles"` to the indices, the SDK will search access profiles too. If you change the query to "a*", the search will return all records starting with the letter "a".
You can also change the sorting logic in the brackets next to `sort`.

71
docs/tools/sdk/typescript/updating-resources.md Normal file
View File

@@ -0,0 +1,71 @@
---
id: typescript-sdk-patch
title: Updating resources with The TypeScript SDK
pagination_label: Update a resource
sidebar_label: Update a resource
sidebar_position: 3
sidebar_class_name: typescriptsdk
keywords: ['tsc', 'typescript', 'sdk', 'update']
description: Learn how to use the TypeScript SDK to update resources.
slug: /tools/sdk/typescript/update
tags: ['SDK']
---
You can use the SDK to update resources.
Here is an example update WorkGroup script which will update the description for the Workgroup created in [Create a Resource](./creating-resources.md):
```typescript
import {Configuration, GovernanceGroupsBetaApi, GovernanceGroupsBetaApiCreateWorkgroupRequest, GovernanceGroupsBetaApiPatchWorkgroupRequest, PublicIdentitiesApi} from "sailpoint-api-client"
const updateWorkGroup = async () => {
let apiConfig = new Configuration()
let api = new GovernanceGroupsBetaApi(apiConfig)
let workgroup = (await api.listWorkgroups({filters: 'name eq "DB Access Governance Group"'})).data[0]
if (workgroup.id !== undefined) {
let updatedWorkgroup: GovernanceGroupsBetaApiPatchWorkgroupRequest = {
id: workgroup.id,
jsonPatchOperationBeta: [{
op: "replace",
path: "/description",
value: "This is an updated description for the workgroup."
}]
}
let val = await api.patchWorkgroup(updatedWorkgroup)
console.log(val.data)
} else {
console.log("Workgroup was not found, id is missing for patch request.")
}
}
updateWorkGroup()
```
Run this command to compile and run the code:
```bash
tsc src/index.ts && node src/index.js
```
The updated WorkGroup will be returned by the SDK:
```typescript
{
description: 'This is an updated description for the workgroup.',
owner: {
displayName: 'Brian Mendoza',
emailAddress: null,
type: 'IDENTITY',
id: '0003c25c365e492381d4e557b6159f9b',
name: 'Brian Mendoza'
},
memberCount: 0,
connectionCount: 0,
id: '541ded73-d4b4-41d6-a10c-8085c02815bb',
name: 'DB Access Governance Group',
created: '2023-12-01T18:14:06Z',
modified: '2023-12-01T18:14:06Z'
}
```