# HTTP Operations In **HTTP Operations**, you can add, edit, delete, and reorder HTTP operations. The connector supports the following operations: - Test Connection - Account Aggregation - Account Delta Aggregation - Group Aggregation - Get Object - Get Object-Group - Create Account - Update Account - Delete Account (using a Before provisioning rule) - Enable Account - Disable Account - Unlock Account - Change Password - Add Entitlement - Remove Entitlement - Pass-through Authentication - Custom Authentication - Get Partitions - Partitioned Account Aggregation > [!NOTE] > > **Notes** > > - The Web Services source supports the Before Provisioning rule, which enables you to delete an account using a rule. For example, you can change the provisioning plan's account operation from `disable` to `delete`. The UI fields are the same and applicable to all the operations that you choose to configure. > - For Entitlement Aggregation, you need to configure the schema manually using the SailPoint APIs. Contact SailPoint Support / Expert Services for assistance. > - For the Web Services source, you can configure the native identity in the provisioning plan using a placeholder such as `$plan.planNativeIdentity$`. > - Access to ExternalDTD is disabled during XML parsing. ## Support for Cookies The Web Services source supports cookies for HTTP requests. The Web Services source supports cookies for multiple endpoints configuration. The source manages the cookies internally for the endpoints configured for the same operation. Cookies from the previous endpoints can be used in all the subsequent endpoints of the same operation type. The Web Services source supports the JSON array as a top element in the HTTP requests. By default, the Web Services source supports cookies. Cookies can be disabled by adding the `disableCookies` attribute key with `true` as a value. This is not applicable for the authentication API call operation. ## Add Operations Configure one or more HTTP operations to manage your source data. The options available to configure the operation vary, depending on your selected **Operation Type**. To add a new HTTP operation, select **Add Operation**. > [!NOTE] > > **Screenshot** > > [![Add Operations]()]() The following topics describe the different configuration tabs that may appear when configuring an operation. ### General Information Enter basic configuration information for the HTTP operation. > [!NOTE] > > **Screenshot** > > [![General Information]()]() 1. In the **Operation Name** field, enter a unique name for the operation that you want to execute. You can change the name of an operation later if needed. > **Note** > > SailPoint recommends that you create a unique name for the operation to help you distinguish it from other operations. For example, if you have two account aggregation endpoints for your source, you can name them "Account Aggregation-1" and "Account Aggregation-2". > **Caution** > > Renaming an existing operation breaks any configured relationships, including endpoint and parent-child relationships. To ensure proper functionality, you must reconfigure any parent-child relationships after renaming an operation. 2. In the **Operation Type** dropdown list, select the name of the operation that you want to execute. > **Note** > > You must configure a Partitioned Account Aggregation operation to support partitioning for static and dynamic. Additionally, to support dynamic partitioning you must also configure a Get Partition operation. 3. Unless it's required for your configuration, leave **Use cURL Command** disabled. > **Note** > > If your configuration requires cURL, refer to [Add an Operation with cURL](<#add-an-operation-with-curl>). 4. In the **Context URL** field, enter the authentication (Context) URL specific to your operation. The connector appends the context URL to the source's Base URL. This can be empty depending on the endpoint of the managed system. For example: `/2/team/members/list` The following are a few keywords that are used in the Context URL along with the placeholder `$`: - `plan` - `response` - `application` - `getobject` - `authenticate` > **Important** > > If the Context URL contains certain special characters, you may need to disable the `skipEncodingDecodingUrl` key. Refer to the [Troubleshooting]() topic. Special characters that may cause issues with the Context URL may include, but aren't limited to, commas (`,`), open and close parentheses or brackets (`()`, `[]`, and `{}`), or pound signs (`#`) for more information. 5. In the **HTTP Method** field, select the appropriate method from the dropdown list. HTTP method is supported by the respective operation. For example, you can select **GET**, **PUT**, **POST**, **DELETE**, or **PATCH**. 6. Select **Save**. #### Support for Expression Language in URLs The web services connector supports expression language in URLs. To use expressions in a URL, wrap them with `_#`. The following objects can support expression language when you use them with placeholders: - Response - Plan - Application For example: ```text https://domain.com/2/team/members/list/_#$response.data$.length()_# /2/team/members/list/_#'hello'.concat('world')_# /2/team/members/list/_# 5 >= 4_# ``` #### Add an Operation with cURL If required, you can enable **Use cURL Command** while configuring the general information. When you enable **Use cURL Command** in most operations, the options for **Context URL** and **HTTP Method** are removed, and you only need to provide the cURL command. The endpoint cURL command for an operation which contains the complete request URL, HTTP Method, Header, and Body is provided in the following example: ```text curl --location --request POST 'https://api.dropbox.com/2/team/members/list' \ --header 'Authorization: $application.accesstoken$' \ --header 'Content-Type: application/json' \ --data-raw '{"limit":1}' ``` In this example, consider the following: - Complete request URL: `https://api.dropbox.com/2/team/members/list` > **Note** > > The URL must be in `http://` or `https://` format. You can add a placeholder URL, but it must have `http://` or `https://` at the beginning of the URL string. You can't use a placeholder URL on its own. - HTTP Method: ```text POST --header 'Authorization: $application.accesstoken$' \ --header 'Content-Type: application/json' \ ``` - Header - Body: ```text --data-raw '{"limit":1}' ``` ### Header The header holds the key and value for a given HTTP operation that you want to execute. The connector sends these key-value pairs as part of the header in HTTP requests. > [!NOTE] > > **Screenshot** > > [![Header]()]() The following example displays a sample key-value pair, where `Authorization` is the header **Key** and `$application.accesstoken$` is the **Value**. ```text Authorization - $application.accesstoken$ Content-Type - application/json ``` > [!NOTE] > > If you don't provide the content type in the Header, the source sets Content-Type as `application/json`. 1. Enter the header **Key** used for the operation. 2. Enter the **Value** of the header key used for the operation. 3. Select **Save**. #### Content Types - JSON request, JSON response: `Content-Type= application/json (optional), Accept (optional)` - XML request, XML response: `Content-Type= application/xml or text/xml or */xml (required), Accept (optional)` - JSON request, XML response: `Content-Type= application/json (optional), Accept = application/xml or text/xml or */xml (required)` - XML request, JSON response: `Content-Type= application/xml or text/xml or */xml (required), Accept = application/json (required)` #### Support for Expression Language in the Header Values The web services connector supports expression language in the Header. To use expressions in the Header, wrap them with `_#`. The following objects can support expression language when you use them with placeholders: - Response - Plan - Application For example, the following example displays sample key-value pairs: ```text Count - _#2+2_# Service-Name - _#$application.serviceName$.concat('service')_# ``` ### Body This is the standard HTTP body used for posting the data with a request. The Body can be configured as one of two types, **Form Data** or **Raw** data entry. Either of these is used for a specific operation. > [!NOTE] > > **Screenshot** > > [![Body]()]() #### Form Data 1. Select **Form Data**. 2. Add the respective data **Key** and **Value**. The Web Services source will not display an error when an endpoint's body type is selected as **Form Data** and the form entries are empty. The key-value pairs are sent as part of the Body in JSON format. XML does not support form data. #### Raw 1. Select **Raw**. 2. Enter the data in the **Body** field. Select **Save**. > **JSON Example** > > You can use this entry without a placeholder: > > ```json > { > "limit": 10, > "cursor": "abcd1234" > } > ``` > > You can use this entry with a placeholder: > > ```json > { > "group_id" : "$plan.groups$", > "permission":"$plan.permission$", > "roles": "$plan.roles$" > } > ``` > [!NOTE] > > **XML Example** > > ```xml > > > > ... > > > > ... > > > ``` #### Additional Information for Body The following keywords are used in the Body along with the placeholder `$`: - `plan` - `response` - `application` - `getobject` - `authenticate` #### Handling the "$" Character in the URL and Body The Web Services source correctly extracts and handles the `$` character in the URL and Body, along with the placeholders. #### Placeholder Details ##### The JSON Request with the Placeholder in the Body/Payload If the body contains a placeholder that is not present in the provisioning plan, response, or source, the source removes the key value from the JSON payload. For example: ```json { "type": "$plan.type$", "id": "$plan.nativeIdentity$", "title": "$plan.title$", "externalid": "12345" } ``` If the plan does not contain the title attribute request, the source removes the title key and value. For example: ```json { "type": "student", "id": "STUD121", "externalid": "12345" } ``` ##### The XML Request with the Placeholder in the Body/Payload If the body contains a placeholder that is not present in the provisioning plan, response, or source, the source removes the value from the XML payload. Refer to the following example: ```xml $plan.fname$ $plan.lname$ $plan.nativeIdentity$ permanent worker ``` If the plan does not contain a `lname` value in the attribute request, the source removes the `lname` value as displayed in the following example: ```xml John wid121 permanent worker ``` > [!CAUTION] > > Depending on the behavior of the API, some servers may interpret keys with a missing value as a sign that the attribute value should be blank instead of a sign that the value should be null, which may cause undesired effects. ##### URL If the URL contains a placeholder that is not present in the provisioning plan, response, or source, the source removes the value from the Request URL. ##### Header If the header contains a value that is not present in the provisioning plan, response, or source, the source removes the key value from the Request Header. #### Support for Expression Language in the Body The web services connector supports expression language in the Body. To use expressions in the Body, wrap them with `_#`. The following objects can support expression language when you use them with placeholders: - Response - Plan - Application The following example is of a JSON request using expression language in the Body/Payload: ```json { "type": "$plan.type$", "id": "$plan.nativeIdentity$", "name": "_#'hello'.concat('world')_#" "size": _#$response.data$.length()_#, "isActive" : _# 2 >= 2 _# "externalid": "12345" } ``` Do not provide quotes outside the expression for values like Boolean and numbers. For example: ```json { "size": _#$response.data$.length()_#, "isActive" : _# 2 >= 2 _# "count" : _#'Hello'.length()_# } ``` The following is an example of an XML request using expression language in the Body/Payload: ```xml _#'hello'.concat('world')_# $plan.lname$ _#$response.data$.length()_# permanent worker ``` ### Response Information Response Information has a **Root Path** and a **Success Code**. > [!NOTE] > > **Screenshot** > > [![Response Information]()]() The Root Path must be common for all the attributes mentioned in the Response Attribute Mapping for a particular operation. The Success Code is the successful HTTP response code expected by respective Web Service operations. The Success Code field accepts HTTP status codes in CSV format. For example, consider the HTTP response code `200, 201, 203`. If the list does not contain any value, the status codes from `200` to `299` are checked. Successful status codes start with `2`. You can provide `2**` as a Success Code. The Web Services source supports a `null` HTTP response body with custom error messages. For the Web Services source, the pagination with a `null` Root Path in Response Mapping works correctly. The default value for root path is `$`. 1. Enter the **Root Path**. This is the common path present in the JSON / XML response. For example: - **JSON** - `$.members.profile` - **XML** - `//wd:Response_Data/wd:Worker/wd:Worker_Data` 2. Enter the **Success Code**. This is the HTTP success code that serves as a response to the request. 3. Select **Save**. ### Response Mapping Response Mapping is a response attribute returned in JSON/XML format from the managed system for specific operations like create user, update user, or account aggregation. > [!NOTE] > > **Screenshot** > > [![Response Mapping]()]() 1. In the **Schema Attribute** field, enter the attributes expected in the JSON or XML response from the URL as a part of the schema. 2. In the **Attribute Path** field, enter the JSON or XML path of the specific attribute in the returned response. The Root Path configured in [Response Information](<#response-information>) is prefixed to the attribute path you enter. For example, based on the examples in Response Information: - **JSON**: | Root Path | Attribute Path | Resulting JSON Path | | --- | --- | --- | | `$.members.profile` | `member_id` | `$.members.profile.member_id` | - **XML**: | Root Path | Attribute Path | Resulting XPath | | --- | --- | --- | | `//wd:Response_Data/wd:Worker/wd:Worker_Data` | `sf:FirstName` | `//wd:Response_Data/wd:Worker/wd:Worker_Data/sf:FirstName` | 3. Select **Save**. In the Web Services source, you have to add the schema attributes manually for the respective Web Services-based target system. The source accurately handles any incorrect JSON attribute paths in the endpoint's response mapping configuration. ### XPath Namespace Mapping Configure the XML **Namespace Prefix** and its corresponding **Namespace URL**, which identify uniquely named elements and attributes in XML requests and responses. > [!NOTE] > > **Screenshot** > > [![XPath Namespace Mapping]()]() > [!NOTE] > > **Notes** > > - Absence of non-standard XML Namespaces results in errors while response parsing. > - If any non-standard XML Namespace exists in the response, configure the same in the XML Namespace mapping where the **Key** is the Namespace Prefix and the **Value** is the Namespace URL. > - If a default Namespace is present, add a temporary Namespace Prefix with the default Namespace URL in the XML Namespace mappings. Use this temporary prefix in the XPath elements within the scope of the default Namespace. 1. Add the **Namespace Prefix** and **Namespace URL** pair to be used in the XML operation. 2. Select **Save**.