Version 22.0.8473

• Overview
• Connector Settings
  • Settings Tab
    • Configuration
    • Authentication
    • Header
    • Body
    • TLS Server Authentication
  • Automation Tab
    • Automation Settings
    • Performance
  • Advanced Tab
    • TLS Client Authentication
    • Proxy Settings
    • Advanced Settings
    • Message
    • Logging
    • Miscellaneous
• Establishing a Connection
  • Authenticating
• Static Requests
• Dynamic Requests
  • Raw Input Data
  • Dynamic Form Data
    • Dynamic Templates with XML Map
  • URL
  • Headers
• File Requests

REST Connectors support building dynamic REST requests to consume RESTful API web services.

Overview

REST connectors expose a simple interface to build the headers, authorization, body, and HTTP method for a REST request. The request body can be set statically within the connector configuration or dynamically generated based on the files processed by the connector.

Connector Settings

Settings Tab

Configuration

Settings related to the core configuration of the connector.

• Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
• Connector Description An optional field to provide free-form description of the connector and its role in the flow.
• Method & URL The HTTP method and target HTTP URL for the REST request.

Authentication

Settings related to authenticating with the REST service.

• Authorization Type The type of authentication to use with the REST service. Please see the Authenticating section for more details.

Header

The Header section supports adding an arbitrary list of HTTP headers to include in the outgoing REST request. Headers are specified as name-value pairs. This section can be used to specify the Content-Type of the message body when the Body Type is set to Raw.

Body

Settings related to generating the body of the REST request. Not applicable when the HTTP method is set to ‘GET’.

• Body Type None - No body will be supplied with the REST request.
  
  form-data - The body is supplied as a set of name-value pairs (fields). If the field is set to static, then both the Name and the Value are specified in the UI. For dynamic fields, the Name is specified in the UI and the Value is dynamically read from the input file processed by the connector. For more information, see the Dynamic Form Data section. You can also select File to pass a file as the form data.
  
  x-www-urlencoded - The body is configured in the same way as form-data, however the name-value pairs are encoded as a URL query string instead of multipart form data.
  
  raw - The body is set to the contents of the input file processed by the connector. The content-type of the body can set via the associated dropdown menu, or specified as a custom header in the Header section.

TLS Server Authentication

Settings related to verifying the TLS server’s identity.

• TLS Server Certificate The public key certificate used to verify the identity of a TLS server. This setting can be left blank, to allow the underlying OS/JVM to perform certificate validation, or it can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

• Send A toggle that instructs the connector to automatically send files when they are ready.
• Retry Interval The interval the connector will wait before retrying a failed send.
• Max Attempts The number of attempts the connector will make to send the message. Setting this value to 1 instructs the connector to only make the initial send attempt without retrying. The connector waits the duration specified by Retry Interval between each attempt.
• Receive A toggle that instructs the connector to automatically process files when they are ready and send them to the Output tab.
• Receive Interval The interval at which the connector will process all pending files and send them to the Output tab. The next field depends on the selection here:
  Hourly — A Minutes Past the Hour dropdown menu allows you to specify the number of minutes past the hour to process receive files.
  Daily — A Time field appears for specifying the time of day (in UTC) to process receive files.
  Weekly — Two fields appear. Day allows you to select the day of the week for processing, and Time allows you to specify the time (in UTC) to process receive files.
  Monthly — Two fields appear. Day allows you to select the day of the month for processing, and Time allows you to specify the time (in UTC) to process receive files.
  Minute — A Minutes field appears for specifying the number of minutes between processing intervals.
  Advanced — A five-position Cron Expression field allows you to specify exact processing intervals. Highlight the field in the connector for more information about these expressions.
• Minutes Past the Hour The minutes offset for an hourly schedule. Only applicable when Receive Interval is set to Hourly. For example, if this value is set to 5, the automation service will send requests at 1:05, 2:05, 3:05, etc.

Performance

Settings related to the allocation of resources to the connector.

• Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
• Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.

Advanced Tab

TLS Client Authentication

Settings related to client authentication when two-way TLS authentication is required.

• Private Certificate The private certificate presented during TLS client authentication.
• Certificate Password The password required to access the TLS client certificate.

Proxy Settings

Settings for using a proxy with the connector.

• Use Global A toggle that instructs the connector to use the proxy settings configured under the Settings tab of Arc.
• Proxy Type The type of proxy to use. Select None to not use a proxy. Otherwise, select Tunnel, SOCKS4, SOCKS5, or HTTP.
• Proxy Host The proxy server. Formatting depends on the Proxy Type selected.
• Proxy Port The port to use when connecting to the proxy.
• Proxy User The username to use when connecting to the proxy.
• Proxy Password The password for the associated username.
• Authentication Scheme The protocol to use when connecting to the proxy. Options include Basic, Digest, Proprietary, and NTLM.

Advanced Settings

Settings not included in the previous categories.

• ArcScript in Headers Allows for the evaluation of ArcScript expressions in the headers before the query is issued.
• ArcScript in URL Allows for the evaluation of ArcScript expressions in the URL before the query is issued.
• Chunked Encoding Whether to use HTTP Chunked Transfer Encoding when sending requests. This allows the application to send portions (chunks) of the message sequentially to avoid overloading the connection.
• Chunk Size The size, in bytes, of each chunk when Chunked Encoding is enabled.
• GET Request Body Allows GET requests to use the input message data as the body of the request.
• HTTP Version Whether to use HTTP 1.0, 1.1, or 2.0 when connecting to the REST service.
• Processing Delay The amount of time (in seconds) that the connector will wait to process files in the Input folder.
• Timeout The duration in seconds to wait for a response from the REST server before throwing a Timeout error.
• Response Headers When set, the connector will promote the specified headers from the REST message as metadata on the downloaded message. Multiple headers may be specified, separated by commas.
• Local File Scheme A filemask for determining local file names as they are downloaded by the connector. Hover over the field for a full list of available macros.
• TLS Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Message

Settings that determine how the connector will search for messages and handle them after processing.

• Save to Sent Folder A toggle that instructs the connector to keep a copy of sent messages in the Sent folder.
• Sent Folder Scheme Instructs the connector to group files in the Sent folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all sent files for the week in that folder. The blank setting tells the connector to save all files directly in the Sent folder. For connectors that process many transactions, using subfolders can help keep files organized and improve performance.

Logging

Settings that govern the creation and storage of logs.

• Log Level Specifies the type of information to log in the connector’s Logs directory:
  • None — Does not create any logs.
  • Error — Creates logs only when the connector encounters an error.
  • Warning — Creates logs only when the connector issues a warning.
  • Info — Logs general information about the workflow, including any errors and warnings (if applicable).
  • Debug — Logs detailed debugging information for both successful and failed workflows.
  • Trace — Logs detailed trace information for both successful and failed workflows.

  Please note that Debug and Trace may log sensitive information including message contents and SSL certificates. Although connection properties (such as passwords) are masked, please review logs of this level for sensitive information before sharing them outside of your organization.

• Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders can help keep logs organized and improve performance.
• Log Messages A toggle that instructs the connector to save a copy of the most recent message in the Logs directory. Note that the connector only keeps one message per subfolder, and the connector overrides the previously-saved message when it runs again.

Miscellaneous

Settings for specific use cases.

• Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Establishing a Connection

A valid target URL is required to establish a connection to any REST service. The service URL may support various HTTP methods, and Method should be configured based on particular web service action or data set to retrieve. Some services may also require authentication or a set of custom headers in order to consume the service.

If the target URL is an ‘https’ URL, the SSL Server Certificate should be set to the public key certificate identifying the server. This field can be set to ‘Any Certificate’ to implicitly trust the target endpoint.

Authenticating

The REST Connector supports username-password authentication in Basic (plaintext) or Digest (encrypted) formats. These credentials are supplied to the REST service as headers in the request.

The REST Connector also supports OAuth authentication, but the OAuth access token and refresh token must be acquired ahead-of-time. Use the REST service’s web portal or development console to find/generate the appropriate OAuth tokens. The connector then handles the process of automatically refreshing the token, so that once the OAuth configuration values are supplied the first time, the connector is continuously able to connect.

Finally, the REST Connector supports AWS Signature authentication when authenticating against Amazon. This option requires configuring credentials provided by Amazon: Access Key, Secret Key, etc.

Static Requests

REST requests that have entirely static content (e.g. requests that use the HTTP GET method) do not require an Input file, since the request content is configured entirely within the connector UI. Simply add any necessary name-value pairs as custom headers in the Header section or form data in the Body section.

Static requests can be automatically sent according to a schedule if Receive Automation is enabled. The response to each request will be stored in the Output/Receive Folder or passed along to the next connector in the flow.

If Send Automation is enabled, files arriving at the Input/Send Folder of the connector will also trigger a static request. The content of the input file is ignored, and the request is sent according to the configuration in the UI.

Dynamic Requests

REST requests can be dynamically populated with data from files that arrive in the Input/Send Folder of the connector.

Raw Input Data

If the Body Type of the request is set to ‘raw’, the content of input files will be sent as the body of the REST request.

The specific content-type of the data can be set via the content-type dropdown. It might be necessary to add a Content-Type header in the Header section if the desired content-type is not listed.

Dynamic Form Data

If the Body Type of the request is set to ‘form-data’ or ‘x-www-urlencoded’, then the connector will look for specific values from the input file to populate the request. For each Body field that is set to ‘Dynamic’, the connector will scan input files for an XML element that shares the same name as the field name, and that follows a particular XML structure:

<Items>
  <FormData>
    <FieldName></FieldName>
  </FormData>
</Items>

To fit this structure, it is strongly recommended to use an XML Map connector prior to the REST connector in the flow, as described below.

When an element that matches the field name and required XML structure is found, the value within this element is used as the value in the Body field. For example, if the Body has a dynamic field with the name ‘CustomerID’, and the input file had the following XML:

<Items>
  <FormData>
    <CustomerID>12354</CustomerID>
  </FormData>
</Items>

Then the REST connector would then set the value of the ‘CustomerID’ field to 12354.

Dynamic Templates with XML Map

The XML Map connector should be used in conjunction with the REST connector to easily build dynamic requests out of other XML data structures. The XML Map connector converts arbitrary custom XML structures into the XML structure that the REST connector expects.

First, configure the REST connector with the set of dynamic (and static) Body fields that should be present in the request. Then, connect an XML Map connector to the REST connector in the Arc flow and save the flow changes. This allows the XML Map connector to detect which fields the REST connector expects in incoming input files.

Then, inside the XML Map connector, the Destination File dropdown includes the REST request schema. Select this as the Destination, and set the Source File to any arbitrary custom XML structure. This will populate the XML Map designer view, and the data that should be included in the REST request can be dragged-and-dropped from the Source structure into the Destination structure. After the mapping is complete, the XML Map connector will automatically convert files that match the Source File into a valid REST request structure.

For more information on using the XML Map connector, please see the XML Map connector documentation

URL

If Allow ArcScript in URL is selected in the Advanced tab of the connector configuration pane, expressions in ArcScript can be evaluated to generate dynamic strings as URLs. For example, the following URL includes the date and time:

http://myendpoint.com/api?day=[_ | now('yyyyMMdd')]

The URL below includes a header on the incoming message for queries triggered through send automation:

http://myendpoint.com/api?customer=[_message.header:customerid]

Headers

If Allow ArcScript in Headers is selected on the Advanced tab of the connector configuration pane, expressions in ArcScript can be evaluated to generate dynamic strings as header values. For example, the following header contains the date and time:

Timestamp [_ | now('yyyyMMdd')]

The header below contains a customer id for queries triggered through send automation:

Customer [_message.header:customerid]

File Requests

When the connector Body Type is set to form-data or x-www-form-urlencoded, you can configure one body field as File. This option causes the input file to be sent in the body of the request.

The Value field for a File body field is greyed out, since the connector uses the input file itself as the form data.

Note: The File option is incompatible with Dynamic requests and other File requests. As a result, if you select this option, you can only combine it with Static fields.