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

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.

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.

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.

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:

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:

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:

  POST
  --header 'Authorization: $application.accesstoken$' \
  --header 'Content-Type: application/json' \
  

• Header

• Body:

  --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.

The following example displays a sample key-value pair, where Authorization is the header Key and $application.accesstoken$ is the Value.

Authorization - $application.accesstoken$
Content-Type - 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:

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.

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:

   {
       "limit": 10,
       "cursor": "abcd1234"
   }
   

   You can use this entry with a placeholder:

   {
       "group_id" : "$plan.groups$",
       "permission":"$plan.permission$",
       "roles": "$plan.roles$"
   }
   

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bsvc="urn:com.workday/bsvc">
<soapenv:Header>
<Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
...
</Security>
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>

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:

{
    "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:

{
    "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:

<worker>
    <fname>$plan.fname$</fname>
    <lname>$plan.lname$</lname>
    <wid>$plan.nativeIdentity$</wid>
    <description> permanent worker</description>
</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:

<worker>
    <fname>John</fname>
    <lname></lname>
    <wid>wid121</wid>
    <description> permanent worker</description>
</worker>

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:

{
    "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:

{
    "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:

<worker>
    <fname>_#'hello'.concat('world')_#</fname>
    <lname>$plan.lname$</lname>
    <size>_#$response.data$.length()_#</wid>
    <description> permanent worker</description>
</worker>

Response Information

Response Information has a Root Path and a Success Code.

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.

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 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.

1. Add the Namespace Prefix and Namespace URL pair to be used in the XML operation.
2. Select Save.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.