Using the Act-On REST Destination Component
The REST Destination Component is an SSIS data flow pipeline component that can be used to write data to Act-On REST services.
See Act-On Rest Connection Manager for how to connect to Act-On and see Act-On REST Source Component for how to retrieve data from Act-On.
There are three configuration pages:
- General
- Columns
- Error Handling
General Page
The General page allows you to specify general settings for the REST Destination component.
- Connection Manager
-
The destination component requires a REST connection to Act-On. The Connection Manager drop-down will show a list of all connection managers that are available to your current SSIS package.
- Destination Object
-
The Destination Object option allows you to specify which object to write data to. A drop-down with the available objects is listed here.
- Action
-
The Action option allows you to specify how data should be written to Act-On.
Note: Supported actions may vary from object to object depending on Act-On's API document.
- Batch Size
-
The Batch Size lets you specify how many records to send per service call to Act-On.
Note: Some objects do not support batch size, so this option will become disabled.
- Input Time Zone
-
The Input Time Zone option specifies the timezone of all incoming datetime fields. Available options are:
- UTC
- Local
- List ID
-
The List ID option is available for some endpoints and lets you specify the ID of the list that this endpoint will use. In Act-On every list can have unique metadata, so specifying the List ID in the editor allows custom metadata to be loaded.
Note: Some objects do not support List ID, so this option will not appear.
- Bulk Polling Interval
-
The Bulk Polling Interval lets you specify how often to poll for the results of long-running bulk tasks. This property is available for bulk endpoints.
Note: Some objects do not support bulk polling interval, so this option will not appear.
- Merge Mode
-
The Merge Mode option determines the behavior of update/merge for certain endpoints. The 5 options available are: APPEND, APPEND_NO_DUPLICATES, UPSERT, UPDATE_ONLY, and REPLACE.
Note: Some objects do not support batch size, so this option will not appear.
- Refresh Component Button
-
Clicking the Refresh Component button causes the component to retrieve the latest metadata and update each field to its most recent metadata.
- Map Unmapped Fields Button
-
By clicking this button, the component will try to map any unmapped attributes by matching their names with the input columns from upstream components.
- Clear All Mappings Button
-
By clicking this button, the component will reset (clear) all your mappings in the destination component.
- Expression fx Icon
-
Click the blue fx icon to launch SSIS Expression Editor to enable dynamic updates of the property at run time.
- Generate Documentation Icon
-
Click the Generate Documentation icon to generate a Word document that describes the component's metadata including relevant mapping, and so on.
Utilizing the Child Input of the Destination Component
If you want to write child objects data to a parent object, you can connect an inbound component containing child objects data to the secondary inputs. Once you have made a connection to a secondary input, you must specify the REST Object you are adding in the Inputs grid on the General page.
When a child is mapped in the Inputs grid on the General page, it will be available in the select input drop-down on the Columns page. This allows for selecting input for both parent and child fields. The parent input will have a field called _LinkId which can be any string and is used to link the parent to its child object. All child inputs will have a field called _{parentObjectName}._LinkId. This field should have a value that matches the value used for the _LinkId of the parent.
Columns Page
The Columns page of the REST Destination Component allows you to map the columns from upstream components to the REST Fields. On this page, you can select the object whose columns you wish to configure in the top left drop-down.
On the top left of the grid, you can see a checkbox, which can be used to toggle the selection of all available fields. This is a productive way to check or uncheck all available fields.
On the Columns page, you would see a grid that contains four columns as shown below.
- Input Column: You can select an input column from an upstream component for the corresponding REST Field.
- REST Field: The field that you are writing data to.
- Data Type: This column indicates the type of value for the current field.
- Unmap: This column can be used to unmap the field from the upstream input column, or otherwise it can be used to map the field to an upstream input column by matching its name if the field is not currently mapped.
Error Handling Page
The Error Handling page allows you to specify how errors should be handled when they happen.
There are three options available:
- Fail on error
- Redirect rows to error output
- Ignore error
When the Redirect rows to error output option is selected, rows that failed to write to the target REST service will be redirected to the 'Error Output({PrimaryInputName})' output of the Destination Component; rows from the Child Input that failed to find the parent records will be redirected to the 'Orphaned Children Error Output' output of the Destination Component. As indicated in the screenshot below, the blue output connection represents rows that were successfully written, and the red 'Error Output{PrimaryInputName}' and 'Orphaned Children Error Output' connection represent erroneous rows.
- Error Output({PrimaryInputName})
- ErrorCode: Contains the error code that is reported by the target service or the component itself
- ErrorColumn: Contains the name of the column that is causing the error. Note that this column is not always populated
- ErrorMessage: Contains the error message that is reported by the target service or the component itself
- Orphaned Children Error Output
- ErrorCode: Contains the error code that is reported by the target service or the component itself from the Child Inputs
- ErrorColumn: Contains the name of the column that is causing the error from the Child Inputs. Note that this column is not always populated
- Input Name: Contains the name of the Child Input that is having an issue.
- Column Name: Contains the name of the column that is having an issue in the specific Child Input.
- Column Value: Contains the value of the column that is having an issue in the specific Child Input.
- Parent Input Name: Contains the Parent Input name of the specific Child Input.
- Parent Column Name: Contains the name of the column that is having an issue in the specific Parent Input.
On the Error Handling page, there is also an option that can be used to enable or disable the following output field for the destination component.
- _ActOnId: Contains the newly created Act-On record's ID, which you can use to write to log or further process using additional data flow components.
Note: If you don't plan to use this field for any further processing, it is generally recommended to turn them off, so you don't get any warning from SSIS by complaining that those fields are never used, doing so should also provide slightly better performance.
- HTTP Diagnostics Output Columns
-
The below columns are available on the Error Handling page in the default output in order to view and work with the HTTP requests sent by our component and the response received so that these could be used in the downstream data flow.
- _HttpRequestUrl: The URL of the request
- _HttpRequestMethod: The HTTP method of the request
- _HttpRequestHeaders: All of the HTTP headers of the request
- _HttpRequestBody: The text body of the request
- _HttpResponseCode: The HTTP status code of the response
- _HttpResponseCodeName: The name of the HTTP status code of the response
- _HttpResponseHeaders: All of the HTTP headers of the response
- _HttpResponseBody: The text body of the response