ImportAccountEntJSON

The ImportAccountEntJSON is a parameter used in Saviynt's REST Connector to map attributes from a REST application to Saviynt Enterprise Identity Cloud (EIC) attributes for importing accounts and entitlements. It defines how data from the target application should be transformed and mapped into Saviynt during the import process.

Key Elements of ImportAccountEntJSON

colsToPropsMap: This element is used to map columns from the target application's data to Saviynt attributes. It specifies how the incoming data fields should be mapped to the Saviynt schema.
statusAndThresholdConfig: This element defines configurations for handling account status and thresholds during the import process. It includes parameters for managing inactive accounts and entitlements, setting threshold values, and specifying status columns.
errorHandling: This element includes various error handling configurations to manage and respond to errors during the import process. Key fields include:
- expiryError: Specifies errors related to token expiry.
- authError: Lists possible authentication errors.
- retryFailureStatusCode: HTTP status codes that trigger a retry mechanism.
- timeOutError: Defines the behavior when a timeout occurs.
- errorPath: Path to extract error messages from the response.
- maxRefreshTryCount: Maximum number of retries for refreshing tokens.

The following tables describes all the attributes in ImportAccountEntJSON:

Attribute : accountParams

Variable	Description
Connection	Populates the connection type value specified in the acctAuth attribute while defining ConnectionJSON.
processingType	Always specify the processing type as.
successResponses	Use this variable to specify the possible response messages on successfully importing accounts.
doNotChangeIfFailed	Use this variable to instruct the connector to not delete or inactivate existing data on failure of the account API, the entType API, or the mapping API. When set to true, the connector does not delete or inactivate existing data.
call	Use this variable to make an API call to the target application API for importing accounts. The connector allows you to specify multiple API calls to import accounts. You must specify each API call for importing accounts as a separate call. There is no fixed name, but the preferred naming convention is: call1, call2, call3.
callOrder	Use this variable to specify the order to call APIs. Specify the value for the first call as zero. The lowest order value is called the first call.
stageNumber	Use this variable to specify the stage number for the API call. Specify the stage number as zero for the first API call.
url	Use this variable to specify the URL of the target application.
httpMethod	Use this variable to specify the API call method for a successful API call such as GET, POST, PUT, DELETE and GETWITHBODY.
httpHeaders	Use this variable to specify the API header parameter to send along with the API call.
listField	Use this variable to specify the path of account objects in the response JSON or XML (received after making the http API call). If the path is a nested path, separate it with a dot (.), for example, “customproperty9”: “address.home”.
keyField	Use this variable to specify the name of the field that uniquely defines whether the incoming account object is a new account or an existing account.
statusConfig	Use this variable to map the status of accounts in IGA with the status in the target application.
colsToPropsMap	Use this variable to map account objects in the target application with account attributes in IGA, so that data from the target application is correctly saved. Review the following guidelines before mapping account attributes:
	- Represent the logical mapping in this format: AccountsTableAttribute in EIC::TargetapplicationAttribute#Parsabledatatypeinsaviynt
	- Represent the target application attributes in the same case and format as they are in the target application.
	- If the field name in the target application contains a dot(.), use a `~dot# separator. For example, odata`~dot#error.
	- If the list objects are at the top of the hierarchy in the response JSON, keep the field empty.
	- If mapping is mandatory for a field, for example, name, accountID, mention the name of the field in the keyField variable.
	- If the path is a nested path, separate it with a dot (.) and to specify the mapping for the path, use an index square bracket, for example, “customproperty9”: “address.home[1].city”.
Pagination	Use this variable to define the pagination parameters. For more information, see the Pagination feature in ImportAccountEntJSON.
inputParams	Set the dependentCall variable as , if you want to import the metadata of an account in successive calls. The value passed in the URL variable of an API is called for each account. The value specified in the nextApiKeyField variable is bound in the URL variable of the successive API calls.
	For example, if you want to get the metadata of account based on account ID, specify the value for the nextApiKeyField variable as accountID. The account ID of the account in the previous call is bound in the URL variable of the successive API calls.
	Set the dependentCall variable as false, if you do not want to mark successive calls to be dependent on the previous call.
disableDeletedAccounts	This variable is no longer required after the introduction of the statusAndThresholdConfig variable. Set this to false in the current codebase.
acctEntMappings	Use this variable to specify the mapping between accounts and entitlements if there is no separate API call made for entitlements import.
	- Use importAsEntitlement to instruct the connector to import entitlements. When set to true, the connector imports associated entitlements. The default value is false.
	- Do not specify any value in listPath.
	- Do not specify any value in idPath.
	- Do not specify any value in keyField.
	- Use colsToPropsMap to map entitlement objects in the target application with entitlement attributes in IGA, so that data from the target application is correctly saved. Specify values in this variable, only if importAsEntitlement is set as true.
	- You must specify the following entry in colsToPropsMap of one of the accounts calls: "customproperty31": "STORE#ACC#ENT#MAPPINGINFO~#~char"
	- Use statusConfig to map the status of entitlements in IGA with the status in the target application.

Attribute : entitlementParams

Variable	Description
Connection	Populates the connection type value specified in the acctAuth attribute while defining ConnectionJSON.
processingType	Always specify the processing type as SequentialAndIterative.
successResponses	Use this variable to specify the possible response messages on successfully importing entitlements.
doNotChangeIfFailed	Use this variable to instruct the connector to not delete or inactivate existing data on failure of the account API, the entType API, or the mapping API. When set to true, the connector does not delete or inactivate existing data.
entTypes	Use this variable to specify all entitlement types to be imported.
entTypeOrder	Each entitlement type can comprise of multiple API calls. Specify order of the entitlement type as 0 for the first entitlement type, specify as 1 for the second entitlement type, and so on.
entTypeLabels	Use this variable to define the label for an EntitlementType property. For example, if you want to rename the customproperty3 to Tag specify "customproperty3": "Tags", under entTypeLabels.
call	Use this variable to make an API call to the target application API for importing entitlements. The connector allows you to specify multiple API calls to import entitlements. You must specify each API call for importing entitlements as a separate call. There is no fixed name, but the preferred naming convention is: call1, call2, call3.
callOrder	Use this variable to specify the order to call APIs. Specify the value for the first call as zero. The lowest order value is called the first call.
stageNumber	Use this variable to specify the stage number for the API call. Specify the stage number as zero for the first API call.
inputParams	Set the dependentCall variable as true, if you want to import the metadata of an entitlement in successive calls. The value passed in the URL variable of an API is called for each entitlement. The value specified in the nextApiKeyField variable is bound in the URL variable of the successive API calls.
	For example, if you want to get the metadata of entitlement based on entitlement ID, specify the value for the nextApiKeyField variable as entitlementID. The entitlement ID of the entitlement in the previous call is bound in the URL variable of the successive API calls.
	Set the dependentCall variable as false, if you do not want to mark successive calls to be dependent on the previous call.
http	Use this variable to specify the http details required to make the API call, for example, URL, http params, headers, content-type, ssl parameters. For most cases, Authorization header value is `${access_token}` which is a place holder and it is populated from the accessToken attribute in ConnectionJSON. Specify httpContentType as application/x-www-form-urlencoded, application/json, application/xml.
listField	Use this variable to specify the path of entitlement objects in the response JSON or XML (received after making the http API call). If the path is a nested path, separate it with a dot (.), for example, “customproperty9”: “address.home”.
keyField	Use this variable to specify the column name in IGA where the entitlement identification ID is saved.
statusConfig	Use this variable to map the status of entitlements in IGA with the status in the target application.
colsToPropsMap	Use this variable to map entitlement objects in the target application with entitlement attributes in IGA, so that data from the target application is correctly saved. Review the following guidelines before mapping entitlement attributes:
	- Represent the logical mapping in this format: EntitlementsTableAttribute in EIC::TargetapplicationAttribute#Parsabledatatypeinsaviynt
	- Represent the target application attributes in the same case and format as they are in the target application.
	- If the field name in the target application contains a dot(.), use a `~dot# separator. For example, odata`~dot#error.
	- If the list objects are at the top of the hierarchy in the response JSON, keep the field empty.
	- Instead of specifying the column name in status field under colstoprop, map the status field to a customproperty and add this value in STATUS_THRESHOLD_CONFIG.
Pagination	Use this variable to define the pagination parameters. For more information, see the Pagination feature in ImportAccountEntJSON.
disableDeletedEntitlements	This variable is no longer required after the introduction of the statusAndThresholdConfig variable. Set this to false in the current codebase.
makeProcessingStatus	Use this variable when there are multiple API calls involved for importing one entitlement type. In most cases, there is an API that gets all the entitlement objects of that type and other APIs might obtain additional data for each entitlement object. In this case, the status of the entitlement should be in process till all the details of that entitlement object is imported. Hence, makeProcessingStatus can be set to true for the first API call and false for the successive API call. The default value is false.

Attribute : acctEntParams

Variable	Description
createUsers	Use this variable to instruct the connector to create users while importing accounts. When set to true, users are created during account import. The default value is false.
	adminName : If createUsers is true, new users are imported and the manager is set as an admin as default. Select the user name if you want to add the user manager other than admin.
Connection	Populates the connection type value specified in the acctAuth attribute while defining ConnectionJSON.
statusAndThresholdConfig	Use this variable, if you are not specifying any value in the STATUS_THRESHOLD_CONFIG connection parameter.
statusColumn	Specify the account attribute mapped with the status of the account. Use this variable, if you are not specifying any value in the statusColumn attribute of the STATUS_THRESHOLD_CONFIG connection parameter.
processingType	Always specify the processing type as SequentialAndIterative.
successResponses	Use this variable to specify the possible response messages on successfully importing entitlements.
entTypes	Use this variable to specify all entitlement types to be imported.
call	Use this variable to make an API call to the target application API for importing entitlements. The connector allows you to specify multiple API calls to import entitlements. You must specify each API call for importing entitlements as a separate call. There is no fixed name, but the preferred naming convention is: call1, call2, call3.
callOrder	Use this variable to specify the order to call APIs. Specify the value for the first call as zero. The lowest order value is called the first call.
stageNumber	Use this variable to specify the stage number for the API call. Specify the stage number as zero for the first API call.
http	Use this variable to specify the http details required to make the API call, for example, URL, http params, headers, content-type, ssl parameters. For most cases, Authorization header value is `${access_token}` which is a place holder and it is populated from the accessToken attribute in ConnectionJSON. Specify httpContentType as application/x-www-form-urlencoded, application/json, application/xml.
listField	Use this variable to specify the path of entitlement objects in the response JSON or XML (received after making the http API call). If the path is a nested path, separate it with a dot (.), for example, “customproperty9”: “address.home”.
acctIdPath	Use this variable to define the path of the account ID in the response JSON.
entIdPath	Use this variable to define the path of the entitlement ID in the response JSON.
ownerIdPath	Use this variable to define the path of the owner of the entitlement in the response JSON.
acctKeyField	Use this variable to define the key field that uniquely identifies the account.
entKeyField	Use this variable to define the key field that uniquely identifies the entitlement value.
ownerKeyField	Use this variable to define the key field that uniquely identifies the owner of the entitlement.

Attribute : entOwnerParams

Variable	Description
Connection	Populates the connection type value specified in the acctAuth attribute while defining ConnectionJSON.
successResponses	Use this variable to specify the possible response messages on successfully importing entitlement owner.
doNotChangeIfFailed	Use this variable to instruct the connector to not delete or inactivate existing data on failure of the API. When set to true, the connector does not delete or inactivate existing data.
entTypes	Use this variable to specify all entitlement types to be imported.
callOrder	Use this variable to specify the order to call APIs. Specify the value for the first call as zero. The lowest order value is called the first call.
stageNumber	Use this variable to specify the stage number for the API call. Specify the stage number as zero for the first API call.
ownerKeyField	Use this variable to define the key field that uniquely identifies the owner of the entitlement.
http	Use this variable to specify the http details required to make the API call, for example, URL, http params, headers, content-type, ssl parameters. For most cases, Authorization header value is `${access_token}` which is a place holder and it is populated from the accessToken attribute in ConnectionJSON. Specify httpContentType as application/x-www-form-urlencoded, application/json, application/xml.
listField	Use this variable to specify the path of entitlement objects in the response JSON or XML (received after making the http API call). If the path is a nested path, separate it with a dot (.), for example, “customproperty9”: “address.home”.
acctIdPath	Use this variable to define the path of the account ID in the response JSON.
entIdPath	Use this variable to define the path of the entitlement ID in the response JSON.
ownerIdPath	Use this variable to define the path of the owner of the entitlement in the response JSON.
acctKeyField	Use this variable to define the key field that uniquely identifies the account.
entKeyField	Use this variable to define the key field that uniquely identifies the entitlement value.

Attribute : entMappingParams

Variable	Description
Connection	Populates the connection type value specified in the acctAuth attribute while defining ConnectionJSON.
callOrder	Use this variable to specify the order to call APIs. Specify the value for the first call as zero. The lowest order value is called the first call.
stageNumber	Use this variable to specify the stage number for the API call. Specify the stage number as zero for the first API call.
http	Use this variable to specify the http details required to make the API call, for example, URL, http params, headers, content-type, ssl parameters. For most cases, Authorization header value is `${access_token}` which is a place holder and it is populated from the accessToken attribute in ConnectionJSON. Specify httpContentType as application/x-www-form-urlencoded, application/json, application/xml.
listField	Use this variable to specify the path of entitlement objects in the response JSON or XML (received after making the http API call). If the path is a nested path, separate it with a dot (.), for example, “customproperty9”: “address.home”.
ent1IdPath	Use this variable to define the path of the parent entitlement ID in the response JSON.
ent2IdPath	Use this variable to define the path of the child entitlement ID in the response JSON.
ent1KeyField	Use this variable to define the key field that uniquely identifies the entitlement value of the parent entitlement.
ent2KeyField	Use this variable to define the key field that uniquely identifies the entitlement value of the child entitlement.
targetEntType	Use this variable to reference the name of child entitlement type for mapping.
mappingTypes	Use this variable to define the type of mapping to be used. The possible values are:
	- ENTMAP - enables bi-directional mapping through entitlementmap.
	- ENT2 - makes the target entitlement type as a child of current entitlement.

Common features

Support for Multiple API Call

Supports calling multiple dependent APIs for the same parent API call to import extended properties from the target application.

Multiple API Calls in accountParams - Sample

Add multiple calls in the accountParams attribute. In this example, the first API call fetches a list of users, and the second call fetches details for each user using data from the first call. This example uses the ${accountName} binding variable to iterate the accounts imported as part of call1. Set the dependentCall variable under inputParams to true when the call2 is dependent on call1.

{
  "accountParams": {
    "connection": "acctAuth",
    "createUsers": true,
    "adminName": "admin",
    "processingType": "SequentialAndIterative", 
    "statusAndThresholdConfig": {
      "deleteLinks": false,
      "accountThresholdValue": 30,
      "correlateInactiveAccounts": false,
      "inactivateAccountsNotInFile": false,
      "deleteAccEntForActiveAccounts": true
    },
    "call": {
      "call1": {
        "callOrder": 0,
        "stageNumber": 0,
        "http": {
          "url": "https://api.**************.com/v1/enterprise/345992/users",
          "httpHeaders": {
            "Authorization": "${access_token}"
          },
          "httpContentType": "application/x-www-form-urlencoded",
          "httpMethod": "GET"
        },
        "listField": "users",
        "keyField": "accountID",
        "colsToPropsMap": {
          "accountID": "id~#~char",
          "name": "id~#~char"
        },
        "disableDeletedAccounts": true
      },
      "call2": {
        "callOrder": 1,
        "stageNumber": 3,
        "http": {
          "url": "https://api.**************.com/v1/user/${accountName}",
          "httpHeaders": {
            "Authorization": "${access_token}"
          },
          "httpContentType": "application/x-www-form-urlencoded",
          "httpMethod": "GET"
        },
        "inputParams": {
          "dependentCall": true
        },
        "listField": "",
        "keyField": "accountID",
        "nextApiKeyField": "accountID",
        "colsToPropsMap": {
          "accountID": "id~#~char",
          "name": "username~#~char",
          "customproperty1": "emailId~#~char",
          "customproperty2": "lastName~#~char",
          "customproperty3": "company~#~char",
          "customproperty4": "timezone~#~char",
          "customproperty5": "defaultEndpoint~#~char",
          "customproperty6": "lastLogin~#~char"
        }
      }
    }
  }
}

Here's the breakdown of this JSON in simple terms

Account Parameters

Connection (connection):
- "acctAuth": This is a placeholder for the actual connection name. This connection contains all the details needed to communicate with the external system.
Create Users (createUsers):
- true: This means new users will be created if they don't already exist in Saviynt.
Admin Name (adminName):
- "admin": The username for the admin account that has the necessary permissions to perform the import.
Processing Type (processingType):
- "SequentialAndIterative": Specifies the method used to process the accounts. Sequential means one after another, and iterative means it will repeat the process.

Status and Threshold Configuration (`statusAndThresholdConfig`)

This section deals with handling inactive accounts and account thresholds.

Delete Links (deleteLinks):
- false: Indicates that existing links (associations) between accounts and entitlements (permissions) should not be deleted.
Account Threshold Value (accountThresholdValue):
- 30: Sets a limit of 30 accounts before any action is taken to inactivate or delete accounts.
Correlate Inactive Accounts (correlateInactiveAccounts):
- false: Indicates that inactive accounts should not be correlated with any actions.
Inactivate Accounts Not in File (inactivateAccountsNotInFile):
- false: Accounts not present in the import file will not be inactivated.
Delete Account Entitlements for Active Accounts (deleteAccEntForActiveAccounts):
- true: Deletes account entitlements for accounts that are still active.

API Calls (`call`)

This section defines how to call external APIs to fetch account data.

Call 1 (call1):
- Order and Stage:
  - callOrder: 0 (first call)
  - stageNumber: 0 (first stage)
- HTTP Details:
  - URL: The endpoint to fetch user data from the external system.
  - HTTP Headers:
    - Authorization: Uses a token (${access_token}) for authentication.
  - Content Type: "application/x-www-form-urlencoded"
  - Method: GET (fetch data)
- List Field (listField): "users" (the field in the response that contains the user data)
- Key Field (keyField): "accountID" (unique identifier for accounts)
- Columns to Properties Map (colsToPropsMap):
  - "accountID": Mapped to "id~#~char"
  - "name": Mapped to "id~#~char"
- Disable Deleted Accounts (disableDeletedAccounts): true (disable accounts that are marked as deleted)
Call 2 (call2):
- Order and Stage:
  - callOrder: 1 (second call)
  - stageNumber: 3 (third stage)
- HTTP Details:
  - URL: Fetches detailed user information using account name.
  - HTTP Headers:
    - Authorization: Uses a token (${access_token}) for authentication.
  - Content Type: "application/x-www-form-urlencoded"
  - Method: GET (fetch data)
- Input Parameters (inputParams):
  - dependentCall: true (depends on the previous call)
- List Field: Empty (not used here)
- Key Field: "accountID"
- Next API Key Field (nextApiKeyField): "accountID"
- Columns to Properties Map (colsToPropsMap):
  - Maps fields like "accountID", "name", "customproperty1" (email), and other custom properties to the corresponding fields in Saviynt.

Error Handling

Error handling is not explicitly shown in the provided JSON, but here’s how it might look:

Expiry Error (expiryError): Handle token expiry issues.
Auth Error (authError): Handle authentication errors.
Retry Failure Status Code (retryFailureStatusCode): List of HTTP status codes that should trigger a retry.
Timeout Error (timeOutError): Handle cases where the API call times out.
Error Path (errorPath): Path in the response where error messages can be found.
Max Refresh Try Count (maxRefreshTryCount): Maximum number of retries for refreshing the token.

Multiple API calls in the entitlementParams

This example uses the ${entitlementID} binding variable to iterate the entitlementIDs imported as part of call1. Set the entitlementname variable under inputParams to the name of entitlement type when the call2 is dependent on call1.

{
  "accountParams": {},
  "entitlementParams": {
    "connection": "acctAuth",
    "processingType": "SequentialAndIterative",
    "entTypes": {
      "zone": {
        "entTypeOrder": 0,
        "call": {
          "call1": {
            "callOrder": 0,
            "stageNumber": 0,
            "http": {
              "url": "https://*****/Group",
              "httpHeaders": {
                "Authorization": "${access_token}",
                "Accept": "text/json"
               },
              "httpContentType": "application/json",
              "httpMethod": "GET"
            },
            "listField": "Rsp.Result",
            "keyField": "entitlementID",
            "colsToPropsMap": {
              "entitlementID": "Guid~#~char",
              "entitlement_value": "Guid~#~char"
            },
            "disableDeletedEntitlements": true
          },
          "call2": {
            "connection": "acctAuth",
            "callOrder": 1,
            "stageNumber": 3,
            "http": {
              "url": "https://****/groupID/${entitlementID}",
              "httpHeaders": {
                "Authorization": "${access_token}",
                "Accept": "text/json"
              },
              "httpContentType": "application/json",
              "httpMethod": "GET"
            },
            "inputParams": {
              "entitlementname": "zone"
            },
            "listField": "",
            "keyField": "entitlementID",
            "colsToPropsMap": {
              "entitlementID": "Rsp.Result.Guid~#~char",
              "entitlement_value": "Rsp.Result.Guid~#~char",
              "customproperty1": "Rsp.Result.AccessPermissionLevel~#~char",
              "customproperty2": "Rsp.Result.Name~#~char",
              "customproperty3": "Rsp.Result.OwnerRole~#~char"
            },
            "disableDeletedEntitlements": true
          }
        }
      }
    }
  },
  "acctEntParams": {
   }
 }

Here's the breakdown of this JSON in simple terms

This JSON configuration is used to call multiple APIs to fetch and manage entitlement data from an external system into Saviynt. In simple terms, this JSON configuration helps Saviynt fetch and manage entitlement data from another system. It defines how to connect to the system, make API calls to fetch data, and handle different types of entitlement data.

Detailed Explanation

Entitlement Parameters

Connection (connection):
- "acctAuth": This is a placeholder for the actual connection name. This connection contains all the details needed to communicate with the external system.
Processing Type (processingType):
- "SequentialAndIterative": Specifies that the processing should be done one after another (sequential) and will repeat the process (iterative).

Entitlement Types (`entTypes`)

Zone (zone):
- Entitlement Type Order (entTypeOrder): 0 (first type to be processed)

API Calls (`call`)

This section defines how to call external APIs to fetch entitlement data. Each call has its own settings for the request.

Call 1 (call1)
- Order and Stage:
  - callOrder: 0 (first call)
  - stageNumber: 0 (first stage)
- HTTP Details:
  - URL: The endpoint to fetch entitlement data from the external system.
  - HTTP Headers:
    - Authorization: Uses a token (${access_token}) for authentication.
    - Accept: "text/json" (specifies the response format)
  - Content Type: "application/json" (format of the request)
  - Method: GET (fetch data)
- List Field (listField): "Rsp.Result" (the field in the response that contains the entitlement data)
- Key Field (keyField): "entitlementID" (unique identifier for entitlements)
- Columns to Properties Map (colsToPropsMap):
  - "entitlementID": Mapped to "Guid~#~char"
  - "entitlement_value": Mapped to "Guid~#~char"
- Disable Deleted Entitlements (disableDeletedEntitlements): true (disable entitlements that are marked as deleted)
Call 2 (call2)
- Connection: Uses the same connection ("acctAuth")
- Order and Stage:
  - callOrder: 1 (second call)
  - stageNumber: 3 (third stage)
- HTTP Details:
  - URL: Fetches detailed entitlement information using entitlementID.
  - HTTP Headers:
    - Authorization: Uses a token (${access_token}) for authentication.
    - Accept: "text/json" (specifies the response format)
  - Content Type: "application/json" (format of the request)
  - Method: GET (fetch data)
- Input Parameters (inputParams):
  - "entitlementname": "zone" (the name of the entitlement type)
- List Field: Empty (not used here)
- Key Field: "entitlementID"
- Columns to Properties Map (colsToPropsMap):
  - "entitlementID": Mapped to "Rsp.Result.Guid~#~char"
  - "entitlement_value": Mapped to "Rsp.Result.Guid~#~char"
  - "customproperty1": Mapped to "Rsp.Result.AccessPermissionLevel~#~char"
  - "customproperty2": Mapped to "Rsp.Result.Name~#~char"
  - "customproperty3": Mapped to "Rsp.Result.OwnerRole~#~char"
- Disable Deleted Entitlements (disableDeletedEntitlements): true (disable entitlements that are marked as deleted)

Pagination

Support for Pagination : Provides the logic to handle the pagination of objects returned from the target application. Various types of pagination are supported to import all accounts and entitlements.

NextUrl Type

Type 1 - Uses Response Body to evaluate the next url

Example - Next Page url in response.

{
    "next_page": "https://saviyntxxx.zendesk.com/api/v2/users.json?page=2&per_page=2",
    "previous_page": null,
    "count": 7
}

Example - No pages to iterate

{
    "next_page": null,
    "previous_page": null,
    "count": 7
}

The logic to iterate into the next page using the URL available in the response body is as follows:

Analyze the complete response for the attribute containing the next page URL.
Use the attribute in the if-else condition as shown in the example below.
Use the value in the response to paginate into the next pages if the next_page attribute contains a value, else the pagination stops.

"pagination": {
    "nextUrl": {
        "nextUrlPath": "${response?.completeResponseMap?.next_page==null?null:response.completeResponseMap.next_page}"
    }
}

Specify the response.completeResponseMap attribute before the traversing path pagination attribute in the response.

Breakdown and Explanation

pagination: This is the root object that contains information related to pagination. It helps in navigating through paginated API responses.
nextUrl: This object contains the URL of the next page in the paginated response.
nextUrlPath: This field is a string that uses a Groovy expression to determine the next page URL. The expression evaluates whether there is a next page available and provides the appropriate URL.

Groovy Expression

The value of 'nextUrlPath' is:

"${response?.completeResponseMap?.next_page==null?null:response.completeResponseMap.next_page}"

${...}
- This syntax is used to embed Groovy expressions inside a string. It allows for dynamic computation of the string value based on the expression.
response?.completeResponseMap?.next_page
- The 'response' object is expected to contain the API response.
- ?. is the safe navigation operator in Groovy. It checks if the preceding object is not null before accessing the property. If response or completeResponseMap is null, it returns null instead of throwing an exception.
- next_page is a property within completeResponseMap that contains the URL of the next page.
== null ? null : response.completeResponseMap.next_page
- This is a ternary conditional operator in Groovy. It works as follows
  - If response.completeResponseMap.next_page is null, the expression evaluates to null.
  - If response.completeResponseMap.next_page is not null, the expression evaluates to the value of response.completeResponseMap.next_page.

Putting It All Together

The nextUrlPath dynamically determines the URL of the next page:

If next_page is null, it sets nextUrlPath to null, indicating there is no next page.
If next_page is not null, it sets nextUrlPath to the value of next_page, providing the URL for the next page.

Type 2 - Uses headers to evaluate the next URL

Response of page one links:

<https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=0;rel="first",http
s://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=2000;rel="next",https:/
/<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=150000;rel="last">

Response of page two links:

<https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=0;rel="first",http
s://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=0;rel="prev",https://<U
RL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=4000;rel="next",https://<URL>
/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=150000;rel="last">

Response from the last call links:

<https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=0;rel="first",http
s://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=148000;rel="prev",https
://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=150000;rel="last">

The logic to iterate into the next page using the URL available in the response headers is as follows:

Split the link based on comma and count the number of links in the response headers. <https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=0;rel="first", --(0)> <https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=2000;rel="next", --(1)> <https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=150000;rel="last" —-(2)>
Find the position of the next URL in the link. In the above link the position of next URL is 1. Similarly find the position of the next URL in page two and the last page.
While constructing the pagination block, utilize the if-else condition to check the size of the links in the headers and use the replace function to remove <, > and >;rel=\"next\" and replace it with null to get a valid URL as shown below. https://<URL>/api/now/table/sys_user?sysparm_limit=2000&sysparm_offset=2000

The first and last page might have three links as shown in the above header responses. To avoid the error in the last page, mention the function “contains('next')” in the condition to consider the link only if it contains the nextUrl attribute else it stops the pagination.

"pagination": {
    "nextUrl": {
        "nextUrlPath": "${headers?.Link?.split(',').size()==4?headers.Link.split(',')[2].replace('<', '').replace('>;rel=\"next\"','').trim():(headers?.Link?.split(',')?.size()==3 && headers?.Link.contains('next'))?headers.Link.split(',')[1].replace('<', '').

Explanation of the Expression

${headers?.Link?.split(',')}
- headers is expected to contain the HTTP headers returned in the response.
- Link is the specific header containing pagination URLs.
- split(',') splits the Link header value into an array of strings based on commas.
.size() == 4
- This checks if the Link header contains four parts when split by commas. This typically means there are four different pagination URLs (first, prev, next, last).
headers.Link.split(',')[2]
- If there are four parts, the third part ([2] in a zero-indexed array) is assumed to be the "next" URL.
.replace('<', '').replace('>;rel=\"next\"','').trim()
- These methods clean up the URL by removing the < and >;rel="next" parts and trimming any whitespace.
headers?.Link?.split(',')?.size()==3 && headers?.Link.contains('next')
- This checks if the Link header contains three parts and includes a "next" URL. This is a fallback if there are only three parts in the Link header.
headers.Link.split(',')[1]
- If the above condition is true, the second part ([1] in a zero-indexed array) is assumed to be the "next" URL.
replace('<', '').replace('>;rel=\"next\"','').trim()
- These methods clean up the URL by removing the < and >;rel="next" parts and trimming any whitespace.
: null
- If none of the conditions are met, null is returned, indicating there is no next page.

Putting It All Together

The nextUrlPath dynamically determines the URL of the next page:

If the Link header has four parts, it extracts the third part as the "next" URL.
If the Link header has three parts and includes a "next" URL, it extracts the second part as the "next" URL.
If neither condition is met, it returns null, indicating there is no next page.

Type 3 - Uses the pagination parameters in the URL to evaluate the next URL

Sample URL: https://<URL>/organization-api-service/v1/management-units?per_page=100&page=0

Sample response body:

{
    "pagination": {
        "totalPages": 3426,
        "totalElements": 34257,
        "page": 0,
        "size": 10
    }
}

The logic to iterate into the next page using the page parameters in the response body is as follows:

Takes the size of the objectList from the response as the condition.
Uses the math function in JAVA to increment the pagenumber and the size of the page from the response received in the body if the size of the objectList i.e the number of elements in the response is more than 0.

"pagination": {
  "nextUrl": {
    "nextUrlPath": "${response?.objectList?.size()>0?'https://examplesaviyntcom/organization-api-service/v1/management-units?page='+Math.addExact(response.completeResponseMap.pagination.page,1)+'&per_page='+response.completeResponseMap.pagination.per_page:null}"
  }
}

Explanation of the Expression

${response?.objectList?.size()>0? ... : null}:
- This is a conditional expression. It checks if the objectList in the response has more than 0 items.
- If true, it constructs the next URL.
- If false, it returns null, indicating there are no more pages.
URL Construction:
- 'https://examplesaviyntcom/organization-api-service/v1/management-units?page=': This is the base URL for the API endpoint.
- Math.addExact(response.completeResponseMap.pagination.page,1): This Java method adds 1 to the current page number to get the next page.
- '&per_page='+response.completeResponseMap.pagination.per_page: This appends the current number of items per page to the URL.

Putting It All Together In simple terms, this JSON snippet dynamically creates a URL to fetch the next page of data from an API. It checks if there are more items to load, and if so, it constructs the URL for the next page; otherwise, it returns null.

Page Type

Type 1 - When the totalCount Path is available in the response, specify totalCountPath as shown in the below configuration

"pagination": {
    "page": {
      "pageSizeParam": "per_page",
      "pageSize": 50,
      "pageRecordCount": "completeResponseMap.meta.count",
      "pageNumberParam": "page",
      "totalCountPath": "completeResponseMap.meta.total_count",
      "firstPageNumber": 1
    }
  }

Breakdown and Explanation

"pagination": { ... }
- This is the main block that contains all the settings related to pagination.
"page": { ... }
- This block specifies how to handle pages within the pagination.
"pageSizeParam": "per_page"
- This sets the parameter name used in the API request to specify the number of records per page. In this case, it's "per_page".
"pageSize": 50
- This specifies the number of records to fetch per page. Here, 50 records will be fetched in each API request.
"pageRecordCount": "completeResponseMap.meta.count"
- This tells the system where to find the count of records in the response from the API. It looks into the path "completeResponseMap.meta.count" in the response JSON to find this number.
"pageNumberParam": "page"
- This sets the parameter name used in the API request to specify which page of data to fetch. Here, it is "page".
"totalCountPath": "completeResponseMap.meta.total_count"
- This indicates where to find the total number of records in the response from the API. It looks into the path "completeResponseMap.meta.total_count" in the response JSON to find this total count.
"firstPageNumber": 1
- This specifies the number of the first page. Usually, pagination starts at 1, but some APIs might start at 0 or another number.

Putting It All Together

The API will fetch data in chunks (pages) of 50 records.
The parameter per_page will be used to specify the number of records per page in the API request.
The parameter page will be used to specify the page number in the API request.
The total number of records and the count of records per page are found in the paths completeResponseMap.meta.total_count and completeResponseMap.meta.count in the API response, respectively.
Pagination starts from page 1.

Type 2 - When the totalCount Path is available in the header, specify totalCountPath as shown in the below configuration.

"pagination": {
    "page": {
        "pageSizeParam": "size",
        "pageSize": 25,
        "pageRecordCount": "25",
        "pageNumberParam": "page",
        "totalCountPath": "headers.x-total-count",
        "firstPageNumber": 0
    }
}

Breakdown and Explanation

"pagination": { ... }
- This is the main block that contains all the settings related to pagination.
"page": { ... }
- This block specifies how to handle pages within the pagination.
"pageSizeParam": size
- This sets the parameter name used in the API request to specify the number of records per page. Here, it is "size".
"pageSize": 25
- This specifies the number of records to fetch per page. In this case, it will fetch 25 records per request.
"pageRecordCount": 25
- This is the number of records in the current page. Here, it is set to a fixed value of 25.
"pageNumberParam": "page"
- This sets the parameter name used in the API request to specify which page of data to fetch. Here, it is "page".
"totalCountPath": "headers.x-total-count"
- This indicates where to find the total number of records in the API response. It looks in the HTTP headers under "x-total-count".
"firstPageNumber": 0
- This specifies the number of the first page. Here, pagination starts at 0.

Putting It All Together

By specifying pageSize, the configuration ensures that data is fetched in chunks of 25 records, making it easier to handle large datasets.
Using pageSizeParam and pageNumberParam, the configuration sets up the parameters that the API will use to understand how much data to send back and which page of data to return.
By defining pageRecordCount and totalCountPath, the configuration helps in understanding the structure of the response and how to interpret the data returned by the API, including knowing how many total records there are and how many records are in the current page.
The firstPageNumber parameter indicates that the API pagination starts from page 0, which is important for correctly requesting and receiving data.

Sample URL:

https://********/rest/api/2/users?limit=100&page=1

Sample response:

{
  "count": 100,
  "hasMore": true,
  "limit": 100,
  "page": 1,
  "TotalCount": 9837
}

The steps to construct the pagination snippet for the above response is as shown below:

Set pageSizeParam as the limit value.
Set pageSize as 1000.
Set the pageRecordCount as the count value.

Add completeResponseMap to the traversing path of pageRecordCount.
Set PageNumberParam as the page value.
Set totalCountPath as the TotalCount value.

Add completeResponseMap to the traversing path of totalCountPath.

Sample Pagination

  "pagination": {
    "page": {
      "pageSizeParam": "limit",
      "pageSize": 1000,
      "pageRecordCount": "completeResponseMap.count",
      "pageNumberParam": "page",
      "totalCountPath": "completeResponseMap.TotalCount",
      "firstPageNumber": 1
    }
  }
}

ImportAccountEntJSON

Key Elements of ImportAccountEntJSON​

Attribute : accountParams​

Attribute : entitlementParams​

Attribute : acctEntParams​

Attribute : entOwnerParams​

Attribute : entMappingParams​

Common features​

Support for Multiple API Call​

Multiple API Calls in accountParams - Sample​

Account Parameters​

Status and Threshold Configuration (statusAndThresholdConfig)​

API Calls (call)​

Error Handling​

Multiple API calls in the entitlementParams​

Entitlement Parameters​

Entitlement Types (entTypes)​

API Calls (call)​

Pagination​

NextUrl Type​

Type 1 - Uses Response Body to evaluate the next url​

Type 2 - Uses headers to evaluate the next URL​

Type 3 - Uses the pagination parameters in the URL to evaluate the next URL​

Page Type​

Type 1 - When the totalCount Path is available in the response, specify totalCountPath as shown in the below configuration​

Type 2 - When the totalCount Path is available in the header, specify totalCountPath as shown in the below configuration.​

Offset Based​

Key Elements of ImportAccountEntJSON

Attribute : accountParams

Attribute : entitlementParams

Attribute : acctEntParams

Attribute : entOwnerParams

Attribute : entMappingParams

Common features

Support for Multiple API Call

Multiple API Calls in accountParams - Sample

Account Parameters

Status and Threshold Configuration (`statusAndThresholdConfig`)

API Calls (`call`)

Error Handling

Multiple API calls in the entitlementParams

Entitlement Parameters

Entitlement Types (`entTypes`)

API Calls (`call`)

Pagination

NextUrl Type

Type 1 - Uses Response Body to evaluate the next url

Type 2 - Uses headers to evaluate the next URL

Type 3 - Uses the pagination parameters in the URL to evaluate the next URL

Page Type

Type 1 - When the totalCount Path is available in the response, specify totalCountPath as shown in the below configuration

Type 2 - When the totalCount Path is available in the header, specify totalCountPath as shown in the below configuration.

Offset Based