Task Factory Rest

Important:  Rest is available for SQL Server versions 2012 and higher.

Connection Manager

Note:  Rest Source connection manager now supports any connections between SSL, TLS 1.1 and 1.2.

Rest Source Connection Manager

Used with the Rest Source and Rest Destination data flow components.

Basic Authentication Settings

Task Factory Rest Connection Manager Basic Authentication Settings tab

OptionDescription
Configuration FileThe file path to the configuration file. The configuration file can be used to auto-populate the Rest Source and Destination's endpoint URL's. Select the down arrow to view all config files currently in the repository. (Repository's location is C:\Program Files (x86)\Pragmatic Works\Task Factory\OAuth2ConfigFiles. You can add new config files to this location which appear in the dropdown.) For config files that exist in a different location, select the ellipsis to launch a file explorer window to navigate to the file.
Skip AuthenticationSelectable option for endpoints that do not require authentication.
User NameThe username needed to authenticate to the endpoint Url.
PasswordThe password that allows you to authenticate to the endpoint Url.
Use Base 64 Encoded Authentication HeaderSelect when Base 64 Encoded Authentication is used by an endpoint.
Security ProtocolThe Security Protocol used by the API.  The Default option uses the TLS version used by your .NET version by default. See the following chart for more information :
.NET VersionTLS Support Information
.NET 4.6 and aboveSupports TLS 1.2 by default.
 .NET 4.5

TLS 1.2 is supported, but you need to opt-in to use it. Execute the following code before making a connection to a secured resource to make TLS 1.2 the default :

  • ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
.NET 4.0TLS 1.2 is not supported. If you have .NET 4.5 (or above) installed on the system, you can opt in for TLS 1.2 even if your application framework doesn’t support it. SecurityProtocolType in .NET 4.0 doesn’t have an entry for TLS1.2, so you need to use a numerical representation of this enum value:
  • ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072;
.NET 3.5 or belowTLS 1.2 is not supported, and there is no workaround. Upgrade your application to a more recent version of the framework.

Authentication Endpoint

Task Factory Rest Connection Manager Authentication Endpoint (optional) tab

OptionDescription
Rest Authentication Endpoint UrlIn this field, you should enter the Url of the website/ web service that you want to connect to.
Results Returned InThe Rest Source allows you to connect to endpoints with Json and XML formats. This selection determines which format the component uses.
Successful Authentication TokenSome endpoints may require a successful authentication token every time it is accessed. You can dynamically set this token using a variable by applying the following format: <Namespace::VariableName> Example:<@User::SuccessToken>

Headers

Task Factory Rest Connection Manager Headers tab

OptionDescription
Add New HeaderSelect to add a new header name and value. Once added, you can select within the column and configure the name and the value.
Remove HeaderRemoves the selected header to be included in the component's output.

Proxy

Task Factory Rest Connection Manager Proxy tab

OptionDescription
Proxy HostWhen connecting to an endpoint using a proxy, you should enter the proxy Url in this field.
Proxy PortThe port number that corresponds to the Url proxy host.
User NameThe username needed to authenticate to the proxy.
PasswordThe password that allows you to authenticate to the proxy.

Advanced Options

Task Factory Rest Connection Manager Advanced Options

OptionDescription
Ignore Ssl Certificate VerificationSelecting this option ignores the SSL Certificate notification from the API during the connection. Note:  This option applies to APIs that require you to have an SSL Certificate. Select this option if the SSL Certificate is not needed. 
Follow RedirectsSelecting this option implements a 301 redirect on configured endpoints. For example, this option would automatically send your request to an https redirect once the request has reached the http version of the site.  
OAuth Connection Manager

Important:  You need to register a new app with the service being used to obtain Api Keys and Secrets. This can be done by visiting the service's developer website. 

Rest Source OAuth Connection Manager

Used with the Rest Source and Rest Destination data flow components.

Connection Settings

Task Factory Rest OAuth Connection Manager Connection Settings tab

OptionDescription
Configuration FileThe file path to the configuration file. The configuration file can be used to auto-populate the Rest Source and Destination's endpoint URL's. Select the down arrow to view all config files currently in the repository. (Repository's location is C:\Program Files (x86)\Pragmatic Works\Task Factory\OAuth2ConfigFiles. You can add new config files to this location which appear in the dropdown). For config files that exist in a different location, select the ellipsis to launch a file explorer window to navigate to the file. 
Api Key, API Secret, Token, and Token SecretAuthentication information provided to you at the application's developer site. Note:  The Token field can be left empty for API's that do not require one.
Signature TypeIdentifies the hash algorithm used in the vendor's authentication process.
Realm and VerifierOptional properties supplied by the vendor that the connection is authenticating with.
Security ProtocolThe Security Protocol used by the API.  The Default option uses the TLS version used by your .NET version by default. See the following chart for more information :
.NET VersionTLS Support Information
.NET 4.6 and aboveSupports TLS 1.2 by default.
 .NET 4.5

TLS 1.2 is supported, but you need to opt-in to use it. Execute the following code before making a connection to a secured resource to make TLS 1.2 the default :

  • ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
.NET 4.0TLS 1.2 is not supported. If you have .NET 4.5 (or above) installed on the system, you can opt in for TLS 1.2 even if your application framework doesn’t support it. SecurityProtocolType in .NET 4.0 doesn’t have an entry for TLS1.2, so you need to use a numerical representation of this enum value:
  • ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072;
.NET 3.5 or belowTLS 1.2 is not supported, and there is no workaround. Upgrade your application to a more recent version of the framework.

Headers

Task Factory Rest OAuth Connection Manager Headers tab

OptionDescription
Add New HeaderSelect to add a new header name and value. Once added, you can select within the column and configure the name and the value.
Remove HeaderRemove the selected header to be included in the component's output.

Proxy

Task Factory OAuth Connection Manager Proxy

OptionDescription
Proxy HostWhen connecting to an endpoint using a proxy, you should enter the proxy Url in this field.
Proxy PortThe port number that corresponds to the Url proxy host.
User NameThe username needed to authenticate to the proxy.
PasswordThe password that allows you to authenticate to the proxy.

Advanced Options

Task Factory Rest OAuth Connection Manager Advanced Options

OptionDescription
Ignore Ssl Certificate VerificationSelecting this option ignores the SSL Certificate notification from the API during the connection.   Note:  This option applies to APIs that require you to have an SSL Certificate. Select this option if the SSL Certificate is not needed.
Follow RedirectsSelecting this option implements a 301 redirect on configured endpoints. For example, this option would automatically send your request to an https redirect once the request has reached the http version of the site.  
OAuth 2 Connection Manager

Important:  You need to register a new app with the service being used to obtain Api Keys and Secrets. This can be done by visiting the service's developer website. For more information about creating and using OAuth2 connections, see OAuth2 Simplified.

Rest Source OAuth 2 Connection Manager

Used with the Rest Source and Rest Destination data flow components.

Connection Settings

Task Factory Rest OAuth2 Connection Manager Connection Settings tab

OptionDescription
Configuration FileYou can create and use configuration files to setup the OAuth2 connections. Select the down arrow to view all config files currently in the repository. (Repository's location is C:\Program Files (x86)\Pragmatic Works\Task Factory\OAuth2ConfigFiles. You can add new config files to this location which appear in the dropdown.) For config files that exist in a different location, select the ellipsis to launch a file explorer window to navigate to the file. 
Api Key and Api SecretAuthentication information provided to users at the application's developer site.
Access TokenTo obtain this information if you do not already have it, select the Get Token button and complete the information requested in the Token Getter user interface.
Is Bearer TokenSelect this option if the Access Token is a bearer token.
Access Token Expiration DateThe expiration date of the access token.
Security ProtocolThe Security Protocol used by the API.  The Default option uses the TLS version used by your .NET version by default. See the following chart for more information :
.NET VersionTLS Support Information
.NET 4.6 and aboveSupports TLS 1.2 by default.
 .NET 4.5

TLS 1.2 is supported, but you need to opt-in to use it. Execute the following code before making a connection to a secured resource to make TLS 1.2 the default :

  • ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
.NET 4.0TLS 1.2 is not supported. If you have .NET 4.5 (or above) installed on the system, you can opt in for TLS 1.2 even if your application framework doesn’t support it. SecurityProtocolType in .NET 4.0 doesn’t have an entry for TLS1.2, so you need to use a numerical representation of this enum value:
  • ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072;
.NET 3.5 or belowTLS 1.2 is not supported, and there is no workaround. Upgrade your application to a more recent version of the framework.

Token Getter (opened when Get Token button is used.)

Task Factory OAuth2 Token Getter

Note:  Please see your service's online documentation to assist in retrieving the information below.

OptionDescription
Choose Settings FileYou can select pre-configured settings for several popular services including, but not limited to: Google, GoToMeeting, and Paypal Sandbox.
Client / Api KeyAuthentication information provided to you at the application's developer site. Note:  This should match the Api Key from the Connection Settings window.
Client / Api SecretAuthentication information provided to you at the application's developer site. Note:  This should match the Api Key from the Connection Settings window.
Authorization Request UrlThe Url used to request authorization from the service. Example: https://api.citrixonline.com/oauth/authorize?client_id={ApiKey})
Grant / Response Code ParameterThe parameter name used to store the value within the Access Token Request Url Query String.
 Access Token Request UrlThe Url used to request an access token from the service. Example: https://api.citrixonline.com/oauth/access_token
Get / Post SelectboxDetermines whether the call is a Get or Post action.
Access Token Request Url Query StringThe query that is appended to the end of the Access Token Request Url. This query contains all of the required parameters needed to be passed to the service to retrieve the access token.
Get TokenSelecting this button opens the (configured) service's online authentication screen in the window below. To complete the process, enter the credentials of the account used to access the service. If successful, the Token Getter window closes and you return to the Connection Settings window. Note:  Bad requests should redirect to a Url configured either in the application or the access token request Url. You can also copy the Url to help troubleshoot invalid requests.

Headers 

You can create header names and values by entering the information in their corresponding windows.

Task Factory Rest OAuth2 Connection Manager Headers tab

Refresh Token (Results Returned In Json / XML)

Task Factory Rest OAuth2 Connection Manager Refresh Token JsonTask Factory Rest OAuth2 Connection Manager Refresh Token Xml
OptionDescription
Refresh TokenAuthentication information provided to you at the application's developer site. Note:  This should match the Api Key from the Connection Settings window.
Token Request UrlIdentifies the Url that the token uses.
HeadersAllows you to add headers within the refresh token. Select Add New Header to add a header. Select Remove header to remove a header.
Results Returned InSpecifies how results are returned from the application (Json, XML, or String.)
Access Token PathUse this box when adding a regular expression to parse the returned data.
Refresh Token PathIdentifies the refresh token path.
Use Token StoreSelect this option to use a Token store.
Token Store IdIdentifies the Token Store Id.
Token Store Path (Optional)Identifies the Token Store path.
Test Get Refresh TokenSelect this option to test the retrieval of the Refresh Token. 

Refresh Token (Results Returned In String)

Task Factory Rest OAuth2 Connection Manager Refresh Token tab String

OptionDescription
Refresh TokenAuthentication information provided to you at the application's developer site. Note:  This should match the Api Key from the Connection Settings window.
Token Request UrlIdentifies the Url that the token uses.
HeadersAllows you to add headers within the refresh token. Select Add New Header to add a header. Select Remove header to remove a header.
Results Returned InSpecifies how results are returned from the application (Json or XML.)
Access Token PathUse this box when adding a regular expression to parse the returned data.
Refresh Token PathIdentifies the refresh token path.
Group IndexIdentifies the index position to return (0 based).
Use Token StoreSelect this option to use a Token store.
Token Store IdIdentifies the Token Store Id.
Token Store Path (Optional)Identifies the Token Store path.
Test Get Refresh TokenSelect this option to test the retrieval of the Refresh Token.

Proxy

Task Factory Rest OAuth2 Connection Manager Proxy tab

OptionDescription
Proxy HostWhen connecting to an endpoint using a proxy, you should enter the proxy Url in this field.
Proxy PortThe port number that corresponds to the Url proxy host.
User NameThe username needed to authenticate to the proxy.
PasswordThe password that allows you to authenticate to the proxy.

Advanced Options

OptionDescription
Ignore Ssl Certificate VerificationSelecting this option ignores the SSL Certificate notification from the API during the connection.   Note:  This option applies to APIs that require you to have an SSL Certificate. Select this option if the SSL Certificate is not needed.
Follow RedirectsSelecting this option implements a 301 redirect on configured endpoints. For example, this option would automatically send your request to an https redirect once the request has reached the http version of the site.  

Configuration Files

You can choose to create or select a configuration file to help you configure your OAuth2 connection manager. Select a link to download the corresponding config file.


Select a configuration file to configure your OAuth2 Connection Manager by completing the following steps:

  1. Select the ellipsisTask Factory Rest OAuth2 Ellipsis button to open the file explorer. Navigate to the .config file and select OK to open the OAuth2 Token Getter. Task Factory Rest OAuth2 Connection Manager select ellipsis
  2. Enter the RedirectUri, ClientId, and Client Secret configured within your Rest application. Select Get Access Token, to expand the window, and enter the application's credentials.  Note:  You may be prompted to allow or deny access to the application. Task Factory OAuth2 Token Getter Get Access Token
  3. After permission is granted, the OAuth2 Token Getter window closes and the Refresh Token tab populates with the required information. Below is an example of Google Analytics. (The actual Refresh Token has been deleted for security.) Select OK to close the Connection Manager. Task Factory Rest OAuth2 Connection Manager populated
Rest Source

Rest Source

Source IconSource Description
Task Factory Rest Source IconThe REST Source allows you to connect to a web service that utilizes a REST API and extracts data in XML or Json format. See the Rest Source Connection Manager, Rest Source OAuth Connection Manager, and the Rest Source OAuth2 Connection Manager to learn more about configuring the component's connection manager.

API Endpoint / Output Columns

Task Factory Rest Source Api Endpoint

OptionDescription
API Endpoint URLIn this field, you set the URL of the web service. You should also choose whether you're making a call to receive information (Get), or making a request to the service (Post). To add a user variable as a parameter to the API Endpoint URL, use the following syntax:  <@Namespace::VariableName> Example : <@User::Variable>
Get/Post DataSpecifies whether the action is a get or post request. (See your application's API page to determine the appropriate action).
TimeoutSets the amount of time (in seconds) the component should fail if there is no response from the web service.
Number of RetriesIndicates the number of times to retry connecting to the API before the component fails.
Results Returned InSelects the format for the results - XML or Json.
Cookie ContainerUsed to identify the variable that stores a returned cookie response. The variable must be of object datatype.

Json, String, and XML Properties

Json Properties Configuration 

Task Factory Rest Source Json Properties

OptionDescription
Root Json PathJson queries can return multiple levels, therefore, this field Identifies the root to be used.
Output ColumnsIn this window, you can add and remove columns, define their name, token path (defined within the raw data), data type, length, precision, scale, and code page.

Using Wildcards (*)

The Rest Source allows for wildcards when arrays are returned. Example: Using the Json Results below, the Root Json Path would be results[0].appInventory[*]. This information tells the component to use the array found at position 0. Because some child arrays do not have an object name, a wildcard or can be used to return all child array objects.

{
   "results": [
       {
           "appInventory": [
               {
                   "name": "Sample name 1",
                   "identifier": "123",
               },
               {
                   "name": "Sample name 2",
                   "identifier": "456",
               },
               {
                   "name": "Sample name 3",
                   "identifier": "789",
               }
                               ]
               }
       ]
}

Important:  Columns that use DT_STR and DT_WSTR return empty string values when the data returns no value. Columns that contain other datatypes convert the empty string values to NULL.

XML Properties Configuration

Task Factory Rest Source Xml Properties

Important:  Columns that use DT_STR and DT_WSTR return empty string values when the data returns no value. Columns that contain other datatypes convert the empty string values to NULL.

OptionDescription
Root XML QueryXML and Json queries can return multiple levels, therefore, this field Identifies the root to be used.
Output ColumnsIn this window, you can add and remove columns, define their name, token path (defined within the raw data), data type, length, precision, scale, and code page.

String Configuration Properties

Task Factory Rest Source String Properties

Important:  Columns that use DT_STR and DT_WSTR return empty string values when the data returns no value. Columns that contain other datatypes convert the empty string values to NULL.

OptionDescription
RegEx Parse PatternThe regular expression used to parse the returned Json. Leaving this field blank returns all data from the index and only one row with this information returns.
Output ColumnsIn this window, you can add and remove columns, define their name, token path (defined within the raw data), data type, length, precision, scale, and code page.

Headers 

Task Factory Rest Source Headers

Headers are simply information about the type of data returned. You can add and remove headers by selecting the corresponding buttons. Once a header is added, select in its Name and Variable Name fields to configure them. Headers Values can be replaced by variables using the following syntax: 

  • <User::NameOfVariable>

Pagination Settings

Pagination Mode

Retreieve from response and set url querystring.

Task Factory Rest Source Pagination Settings

OptionDescription
Cursor Value Token PathWhen returning large result sets, web services may employ a method called Cursoring to break up the data into smaller chunks. The value token path is the Json token / XML path that exists within the results. Example:
Codeblock
{ "pagingToken":"12345", "results":{"name":"Sentry One"} }
The token path in this instance is pagingToken.
Is Cursor Token Value A UrlSelect this option if the cursor token value is a Url.
Cursor Query String ParameterThe query string parameter is appended to each round trip (after the first) to the Api Endpoint Url. Example: Creating the parameter pagingToken appends it to the end of the Url such as the following: http://webservice/endpoint?pagingToken=12345.)
Cursor Finished ValueThis token or value defined by the user tells the component all of the results have been retrieved. Note:  This can be left blank if the endpoint omits the results token when it's finished.
Pause Between Round Trips (Seconds)The number of seconds between calls to the application.

Retrieve from response and set replacement value.

Task Factory Rest Source Pagination Settings

OptionDescription
Page Token PathThe value used in the Pagination Token.
Pagination TemplateSets the template that can be replaced in the Endpoint Url or Post Body. Example: http://myapp.com/token?value= {%paging%}
Pagination Token Finished ValueIdentifies the final value.
 Pause Between Round Trips (Seconds)The number of seconds between calls to the application.

Manage in component and set replacement value.

Task Factory Rest Source Pagination Settings

OptionDescription
Page Start VariableThe record number where you want to start. Note:  Generally, this value is 1.
Increment ByThe number of items per page.
Max Number Of PagesThe total number of pages. Note:  This value isn’t dynamic, so can’t be entered as a value.
Pagination TemplateThe value appended to the call and stored in the {%paging%} variable which is added to the Endpoint.
Last Page DetectionIdentifies the method the endpoint uses :
  • End paging when status code is  
  • End paging when response contains error message
  • End paging when resultset doesn't contain any rows
Pause Between Round Trips (Seconds)The number of seconds between calls to the application.

Authentication Results

Task Factory Rest Source Authentication ResultsSecured rest endpoints often need an authentication token for each call made to the REST point. This token may change for each call. Create a variable to dynamically set the authentication response token by selecting the Add New Mapping button.  

Test Api

Task Factory Rest Source Test Api

Once properly configured, you can select the Preview Data button to see an output sample as well as return raw XML/Json should you need additional information to help configure the component further.

Endpoints

Task Factory Rest Source Endpoints

OptionDescription
Choose ConfigurationYou can select available endpoints.

Http Error Output

The rest source can capture error responses with the Http Error Output. You are asked to choose between the Rest Source Output and Http Error Output when connecting downstream components. 

Note:  : An execution error causes a package to fail unless the Http Error Output is attached.

Task Factory Data Flow TaskError Response Path Property

The rest source depends on failure http status codes. Codes such as 401, 404, and 500 are used to detect if an error has occurred during execution. If an API doesn't return failure http status codes when an error occurs, you can tell the component what to look for. This allows the component to fail with an error. 

For example: a user makes a call to an api and it returns a valid status code of 200. If the json response is  { "response" : { "error":"Invalid auth token" } }, you can set the Error Response Path to response.error. The component detects the error response and throws an exception that can be handled. At this point, the component throws an exception and does not send the error to an error output.

This only applies to endpoints that return an http status code of 200 through 208, instead of using a failure code such as 401 or 404. 

Task Factory Rest Source Data Flow Component Error Response Path

Note:  The Rest Source makes more than one attempt to connect. If the first one fails, the component makes all attempts to connect until it either reaches the configured timeout or five unsuccessful attempts.

Configuring Rest Source for Visual Studio Team System (VSTS)

Configure Rest Source for Visual Studio Team System by completing the following steps:

  1. Before configuring the Rest Source, you need to set up alternative credentials in VSTS. This can be done by accessing the Security Settings for the account. Task Factory set up alternative credential in Visual Studio Team System
  2. Select Alternate authentication credentials, and then set up the username and password: Task Factory Alternate authentication credentialsAlternatively, the personal access tokens (highlighted above) can be used as the password in the REST Source.
  3. Open the Rest Source component.
  4. Create a new Basic Authentication connection manager: Task Factory Rest Source Create New Rest Connection
  5. Enter the username and password in the connection manager. Task Factory Rest Connection Manager
  6. Close the connection manager and configure the Endpoint Url. Please consult VSTS's API documentation for endpoint information. Task Factory Rest Source Endpoint URL
Rest Destination

Rest Destination

Destination IconDestination Description
Task Factory Rest Destination IconREST Destination enables you to connect to a web service that utilizes a REST API and send data to it. See the Rest Source Connection Manager, Rest Source OAuth Connection Manager, and the Rest Source OAuth2 Connection Manager to learn more about configuring the component's connection manager.

API Endpoint

Task Factory Rest Destination Api Endpoint

OptionDescription
Endpoint URLYou set the URL of the web service and choose the method making the call:
  • Post - (Default) Request that the destination URI perform an action with the provided data.
  • Get - Retrieves data from the destination
  • Put - Stores data at a URI and can be used to create a new entity or update an existing one.
  • Delete - Requests that data be removed
  • Patch - Requests an update to the specified fields of an entity at a URI.

Important:  The Endpoint URL and Post Data uses auto-complete for source columns and variables. Source columns are surrounded in curly braces {{ColumnName}}. Variables use the following format: <@User::MyVariable>.

Post DataThe user defined data used in the post request.
TimeoutSets the number of seconds the component should fail if there is no response from the web service.
Number of RetriesIndicates the number of times to retry connecting to the API before the component fails.
Cookie ContainerUsed to identify the variable that stores a returned cookie response. The variable must be of object datatype.

Headers 

Task Factory Rest Destination Headers

Headers are information about the type of data returned. You can add and remove headers by selecting the corresponding buttons. Select the header's Name and Variable Name fields to configure them after they are added. 

Note:  Source columns and variables can be used as header values. Columns are surrounded in curly braces {{ColumnName}}. Variables use the following format: <@User::MyVariable>.

Valid Status Codes

Task Factory Rest Destination Valid Status Codes

OptionDescription
Valid Status CodesYou can add the code to report when a valid request is made. When several status codes are used, they should be separated with the ("pipe") character. Note:  In most cases, any 200 statuses are valid.
Error Handling:
  • Not Used - Error handling is not used and no error constraint is available.
  • Ignore Failure - All errors are ignored and the package continues to execute.
  • Redirect Row - All errors are directed to an error output.
  • Fail Component - (Default) On error, the component fails execution and stops the package.

Test Endpoint

Task Factory Rest Destination Api Endpoint

OptionDescription
Test Endpoint buttonThe Test Endpoint button produces a sample output based on the user's configuration.  Values can be substituted by entering them in the table above the Test Endpoint button. Note:  Input Column Names cannot be changed.)
Request tabThe Results tab displays the data returned in the request. The Request tab displays the actual request made to the endpoint.

Endpoints

Task Factory Rest Destination Endpoints

OptionDescription
Choose ConfigurationThis view displays the configuration name and endpoint value. This is generated from the configuration file chosen in an OAuth2 connection manager. Parameters are configured by selecting the endpoint and selecting the Choose Configuration button. (This opens a parameter window.)  

Sending Files to a Rest Destination

You can send files with the Rest Destination. The column must use DT_BYTES or DT_IMAGE data types. Additionally, only the column that contains the file can be included in the POST body.

Rest Destination Response Output

The Rest Destination uses the successful output to capture responses from the service.

Task Factory Rest Destination Response output

Output responses are output as NTEXT datatypes. To view the response in a data viewer, you need to use SSIS's native Data Conversion component.

Rest Task

Rest Task

Task Factory IconDescription
Task Factory Rest Task IconREST Task allows you to execute calls to a REST endpoint. See the Rest Source Basic Connection Manager, Rest Source OAuth Connection Manager, and the Rest Source OAuth2 Connection Manager to learn more about configuring the component's connection manager.

Request Settings tab

Task Factory Rest Task Request Settings

OptionDescription
API Endpoint URL In this field, you set the URL of the web service. You should also choose whether you're making a call to receive information (Get) or making a request to the service (Post.)
Get/Post Data Specifies whether the action is a get or post request. Note:  See your application's API page to determine the appropriate action.
Timeout Sets the amount of time (in seconds) the component should fail if there is no response from the web service.
Number of Retries Indicates the number of times to retry connecting to the API before the component fails.
HeadersHeaders are simply information about the type of data returned.
Add New Header button / Remove Header buttonYou can add and remove headers by selecting the corresponding buttons. Once a header is added, select in its corresponding Name and Value/Variable Name fields to configure. Note:  Header Values can be replaced by variables using the following syntax: User::NameOfVariable.

Response Handling tab

Task Factory Rest Task Response Handling

OptionDescription
Save Response To Identifies the variable that populates with the response value.
Filter Response Select this option to filter responses.
Response Format Select Json, XML, or String. Note:  This option enables when Filter Response is selected.
Response Filter Add the words separated by commas to return only the items listed here.
Save Http Response Code Select this option if an http response code is returned.
Choose Variable Identifies the variable that populates with the http response code. Note:  This option enables when Save Http Response Code is selected.

Error Handling

Task Factory Rest Task Error Handling

OptionDescription
Valid Status Code Add the valid HTTP status codes returned by the REST API. Multiple codes can be added by separating them with the pipe ( ) character. Note:   Most of the time, 200 is the only valid status code.
Turn On Debug Mode Package executes in debug mode.

Preview / Test Task Factory Rest Task Preview / Test

Once properly configured, select the Preview Data to view an output sample. The preview also returns raw XML/Json/string data that can assist in configuring the component further.

Rest Examples

Rest Examples

Connecting to Google Analytics Example

The following is an example for configuring a Rest OAuth2 Connection Manager, and Rest Source to your Google Analytics API.

API Info

  1. Log into your Google developer account tied to analytics, and create an App or agent that communicates with Google API.
  2. Enable the Google Analytics Reporting Api by going to library, and selecting Google Analytics Reporting Api. Select enable to activate the API.
  3. Create an OAuth2 Client ID by selecting Credentials > Create Credentials > OAuth Client ID. Select the application type, in this example we are using a Web Application. Provide a name for the credentials, and then enter a redirect URI. Select Create to finalize the creation of the OAuth Client ID. The entered URI needs to be an http or https URL that will respond whenever the API reaches out to it. 
  4. Return to Credentials to display the newly created Client ID under the OAuth2 Client IDs section. Select the client name to obtain the Client ID, Client Secret, and Redirect URI from the API. The Client ID, Client Secret, and Redirect URI are essential to establishing the Rest OAuth2 Connection Manager, and Rest Source.

Connection Manager

  1. Create a new, or open an existing Visual Studio SSIS project and then create a new Rest OAuth2 Connection Manager. Google Analytics uses a Rest OAuth2 Connection Manager.
  2. In the Rest OAuth2 Connection Manager window, select the Google Analytics Configuration file to open the Token Getter Window.
  3. Enter the Redirect URI, the Client ID, and the Client Secret into the appropriate fields in the Token Getter. Select Get Access to establish access. Select Allow Access to the API to continue. If you are connecting to the API for the first time, you may need to log into the API to proceed.

Note:  Providing the above information into the Token Getter auto-populates many fields within the Connection Manager, including the Refresh Token tab.

Rest Source

  1. Consult the applicable API reference guide for information about Endpoints.
  2. Create a new Rest Source. Right click the Rest Source and select edit to configure the Rest Source.
  3. Connect to the OAuth2 Connection Manager by selecting the Connection Manager from the Connection Manager drop-down list. Some fields within the Rest Source auto-populate based on the information provided to the connection manger in the configuration file.
  4. In the Api Endpoint tab, enter the applicable Endpoint URL into the appropriate field, and then select the action you want the rest source to take.
  5. Select the Test API tab to test the data that the API returns. Select Preview Data to display a Raw Response from the API.
  6. Select the Json Properties tab to configure the Root Json path. Enter the applicable Root Json Path, and then select Ok to complete the Rest Source.

Note:  For more information about the processes involved with this example, see the video tutorials below.

Video Tutorials

Using Rest Source with Salesforce

Using Rest Source to connect to Google Analytics