Invoker Step
The Invoker step allows you to choose an Invoker for a process. Invoker components provide the ability to use a service provided by an external system or application. The service is invoked by passing a source message object to the Execute action. The component uses the data provided in the message object to pass the information necessary to use the service to the system or application. An Invoker places any output from the service into the target message object. Typical applications for an invoker component include using a web or SOAP service.
Invoker Step Properties
After adding an 
Invoker step from the Palette to the canvas, you can double-click the step on the canvas and specify the following step properties in the Properties tab displayed at the bottom.
Invoker step from the Palette to the canvas, you can double-click the step on the canvas and specify the following step properties in the Properties tab displayed at the bottom.Name | Description |
|---|---|
Name | Unique name for the step. |
Description | Description of the step (optional). |
Enabled | Select this option to enable the step for execution. If it is not enabled, then the step on the canvas is greyed-out. This option is useful when troubleshooting a process, especially when there are numerous steps in the process. |
Error Handling | Select any of the following: • Abort Process - All the steps after the current step are skipped or the entire process is stopped (depending on how you have set the error logging options) if this step stops due to an error. • Ignore Error - The remaining steps in the current process are executed even if this step stops due to an error. This is selected by default. |
Select Invoker | Select an invoker instance. These instances are displayed when you add message components in the Configuration tab. For more information, see Adding Message Components in Configuring Processes. |
Action | Select the action for the step. |
Parameters | Parameters for the selected action. Specify values for the parameters. |
Properties | Properties for the selected action. Specify values for the properties. |
Note: The Actions, Parameters, and Properties are specific to the component type. For information about this, based on the component instance selected in the Select Invoker drop-down list, click the component type in Invoker Step Components.
Invoker Step Components
DataFlow Invoker
The DataFlow Invoker allows you to execute DataFlow scripts and JSON graphs within a DataConnect process. The DataFlow Invoker uses the DataFlow command line to call and run an existing DataFlow application. The supported DataFlow Invoker version is 6.2.0.
Note: DataConnect supports DataFlow 6.6.
The DataFlow Invoker allows you to run workflows that uses the DataFlow libraries in the following ways:
• Using RushScript to make calls to the DataFlow library JavaScript API (see RushScript topic in the DataFlow documentation.)
• Using a custom Java class to make calls to the DataFlow library Java API (see the DataFlow API Usage topic in the DataFlow documentation.)
• Exporting a workflow from RushAnalytics and executing that workflow with the DataFlow Invoker as a JSON file (see the Enabling Workflows to Execute with DataFlow topic in the DataFlow documentation.)
For more details about building workflows, see the Building DataFlow Applications in Java topic in the DataFlow documentation.
For example, the following process contains a DataFlow Invoker step that uses RushScript to make calls to the DataFlow library JavaScript API:
1. An organization has customer data in a delimited ASCII file that they want to profile to automatically discover the values that appear frequently. The DataFlow Invoker step calls the DataFlow API using a custom script that uses the Summary Statistics operator (see the Using the Summary Statistics Operator topic in the DataFlow documentation). The output of the DataFlow Invoker step generates an XML file that contains the statistics.
2. The XML file is converted to delimited ASCII format using a Transformation step.
3. The Transformation step generates an Excel file that contains the most frequent values in every column, with the count of the occurrence.
Preparing to Use DataFlow Invoker
You must be familiar with the following concepts before using the DataFlow Invoker.
Concept | Description |
|---|---|
DataFlow technology | The framework on which workflows are built is called DataFlow. For more information about this technology and its associated terminology, see the DataFlow documentation. |
DataFlow workflow | You use the DataFlow Invoker to run a DataFlow workflow, also called as a graph. |
Building a process | A DataFlow workflow is run as a step in a process. For more information, see Building Processes. |
Adding a license | To create workflows using the DataFlow Invoker, the integration platform license must include the Engine DataFlow feature. See Uploading License File. |
Using attachments | You can use a RushScript, Java class, or JSON file project attachment as the file to run. |
Using the DataFlow command line | The DataFlow Invoker works by calling the DataFlow command line tool. See the Running from Command Line topic in the DataFlow documentation. |
Prerequisites
Before using the DataFlow invoker, perform the following:
• Install DataFlow: Make sure you have contacted your account executive to obtain the items required to set up Actian DataFlow.
• Access Job Files: Make sure you have JSON, Java class files, or JavaScript files to run the workflow.
Note: If using the method to access the DataFlow libraries involves exporting a JSON file, then an exported RushAnalytics file (.dr) is a JSON file.
• Access Data Files: Make sure you have the source data files you want to use in the process.
• Test the command line: The DataFlow Invoker works by calling the command line tool. When testing the command line, make sure that you are logged in to the system as a user that has the required permissions to read the DataFlow Job Files and source data, and write the target data.
Installing DataFlow and Specifying DR_LOCATION Macro
To install DataFlow, see the DataFlow documentation available at docs.actian.com.
After installing DataFlow, create the DR_LOCATION macro that points to the DataFlow installation location. For example, C:\Actian\dataflow-6.x-x. More information about the DR_LOCATION macro are provided later in this topic (see the DataFlow Install Directory property description.) This macro must be added to one of the following:
• Macro set that is included in all projects that use the invoker
• GLOBAL macro set: Can be used by all processes that call the DataFlow Invoker
Setting up DataFlow Command Line to Run DataFlow Invoker
To set up the DataFlow command line:
1. Extract the contents of the DataFlow 6.x SDK to the Actian installation directory (or a preferred location). The extracted folder contains the required files. For more information, see the Installing and Configuring DataFlow section in the DataFlow documentation.
2. (Optional) Obtain the DataFlow license (DataRush.slc) and add it at the root of the DataFlow installation directory. If you do not have the license, contact Actian Support.
Note: This is required if you do not have the DataFlow feature included in the DataConnect license.
3. (Optional) To use DataFlow from the command line, add <installdir>\dataflow-6.x\bin to the PATH environment variable.
Note: To verify that you have correctly installed the DataFlow command line, run dr -v on the command line. The installed DataFlow version number is displayed. Also, make sure that DataConnect has all DataFlow required environment variables set (includes JAVA_HOME). See the Configuring the Installation section of the Installing DataFlow for Use with Java in DataFlow documentation.
DataFlow Licensing
If license file was not installed when DataFlow was installed, use the $DR_LICENSE_LOCATION macro and specify to the directory containing one or more license files. In this case, DataFlow reads all the license file in the directory.
Configuring DataFlow Invoker
You can specify the following properties when you create an instance of this invoker component in the process file > Configuration tab > Message Components section.
Property | Description |
|---|---|
DataFlow Install Directory | Indicates the DataFlow installation location. By default, $(DR_LOCATION) is displayed. If this macro does not exist, the following error message is displayed: $(DR_LOCATION) macro is not defined. $(DR_LOCATION) macro should be defined with location of DataFlow install. Note: It is possible to have multiple DataFlow installations on the same system. In this case, you may need to use macro sets or overrides in the run-time configuration to set $(DR_LOCATION) to the appropriate DataFlow installation for your process. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported properties. |
Supported Action Parameters
Not applicable
Supported Action Properties
The following table provides the properties that the Execute action supports.
Property | Description |
|---|---|
DataFlow Job File | JavaScript file that must be executed. Multiple values are separated with the system default path separator (a colon (:) on Linux; a semicolon (;) on Windows). If executing a Java class, then specify the fully qualified name of the Java class file to be executed. For example, com.example.MyCustomClass. You can also specify the class as an attachment. For details, see the Class Path property description. |
Run a JSON Graph | Enable JSON file execution. By default, it is Disable. |
Execute a Java Class | Enable Java DataFlow class execution. By default, it is Disable. |
Working Directory | Working directory location where, if relative paths are used in the invoker configuration or the workflow to run, they are resolved relative to this location. Note: UNC paths are not supported. |
Class Path | File paths of additional .jar files to be loaded by the Java Virtual Machine before execution. Multiple values are separated with the system default path separator (a colon (:) on Linux; a semicolon (;) on Windows). |
Java Arguments | A string containing the JVM arguments that DataFlow invoker must use. |
Character Set | Character set required to read JavaScript files. Note: This property is not displayed if Run a JSON Graph or Execute a Java Class is enabled. |
Cluster Execution | Cluster configuration required to run the workflow. Specify the value as a macro or in the following format: dr: //host:IP port number where, • host is the host name or IP address of the server running the cluster manager • port is the specified port number of the cluster manager. |
Engine Configuration | Engine configuration type and settings that you can pass to DataFlow. Note: This property is not displayed if Execute a Java Class is enabled. |
Include Directories | Comma separated list of folders containing scripts to be loaded before job execution. Note: This property is not displayed if Run a JSON Graph or Execute a Java Class is enabled. |
JavaScript Environment Variables | List of variables that are used in the RushScript job files. Specify the variables in the following format: variable1=value1[, variable2=value2] Note: This property is not displayed if Run a JSON Graph or Execute a Java Class is enabled. |
Import Macros | Enable importing of all DataConnect macro definitions. By default, it is Disable. Note: This property is not displayed if Run a JSON Graph or Execute a Java Class is enabled. |
Strict Mode | Set JavaScript strict checking mode to one of following: • Disabled • Warning (default) • Error Note: This property is not displayed if Run a JSON Graph or Execute a Java Class is enabled. |
Properties Override File | Specify the properties file that contains the operator overrides. Note: This property is displayed only Run a JSON Graph is enabled. |
Override Operator Properties | String of source and target outputs (separated by a comma (no spaces)), that will be overridden in the JSON graph. Note: This property is displayed only Run a JSON Graph is enabled. You can consider using this feature if the paths on the RushAnalytics development machine do not match the paths for the job files. When the paths do not match, you can use override operator properties to adjust the locations or manually edit the exported .dr file. The following are examples of supported syntax for this property: SourceNodeName.source=path/file TargetNodeName.target=path/file Example: SourceNodeName.source=C:\DR_SHARED_STORAGE\Input.txt, TargetNode1Name.target=C:\DR_SHARED_STORAGE\Output1.txt, TargetNode2Name.target=C:\DR_SHARED_STORAGE\Output2.txt Note: For formatting purposes, spaces are included after the commas, but in actual use, no spaces are allowed. Tip... • Use the naming conventions for the sources and targets. • Add the source and target entries to the string in the order in which they appear in the JSON (.dr) file. • Do not use spaces in source and target names or paths. |
Use Cases
A few use cases are:
• Create a workflow that calls the DataFlow API using custom JavaScript (the Run a JSON Graph and Execute a Java Class properties must be set to Disable).
• Execute a workflow with a JSON file that has been exported from RushAnalytics (the Run a JSON Graph property is set to Enable).
Note: Make sure the version of the DataFlow SDK matches the version used by RushAnalytics.
• Create a workflow that calls the DataRush API using a custom Java class (the Execute a Java Class property is set to Enable).
Troubleshooting Tips
If you are having trouble executing your job, make sure that:
• DataConnect has permission to access all the files and folders used in the properties.
• DataFlow is set up properly.
If you want to know the specific errors, check the log.
To debug a process run that uses the DataFlow Invoker step:
1. Set the Logging Level in the run-time configuration to DEBUG.
2. Save and run the configuration.
3. Select the Log tab in the console.
4. In the Find field, search for the word "firing". You should see a single instance of the word, which points to the command run on the command line.
5. Check that this command line works outside the DataFlow Invoker, in a command shell.
Error Codes
Error Code | Name | Description | Possible Reason |
|---|---|---|---|
33 | BADOPTIONVAL-UE | An invalid option value was used. | An invalid value is used for an option in the session properties. |
46 | LICENSING | A valid product license was not found. | A valid license is not available for this component and DataFlow is not available. |
50 | UNSPECIFIED | An Unknown error occurred while loading or executing the component. | For details, see the process log file. |
IS API Invoker
The Integration Service API for SAP Invoker (referred to as the IS API Invoker) enables you to make a remote function call to query your SAP installation for a list of function modules and interact with the modules using an Apache Derby database for local storage. Explained here is how to set up the Apache Derby database and how to specify properties for an invoker instance and associated invoker steps.
Setting Up an Apache Derby Database
The IS API Invoker can use an embedded or a network Derby database. The network database must be started before using the invoker.
To set up the Network Apache Derby database
1. Download the Apache Derby software from http://db.apache.org/derby/releases/release-10.4.2.0.html.
2. Unzip the software to the following folder on your machine:
C:\Apache\db-derby-10.4.2.0.bin
3. Follow the configuration instructions at http://db.apache.org/derby/papers/DerbyTut/ns_intro.html#ns.
4. Start the network server in a command window and look for the following message to ensure that the server has started correctly.
C:\Apache\db-derby-10.4.2.0-bin>startNetworkServer.bat
Security manager installed using the Basic server security policy.
Apache Derby Network Server - 10.4.2.0 - <689064> started and ready to accept connections on port 1527 at 2010-04-02 20:16:27.187 GMT
Note: If you need to use a port number other than 1527, be sure to make a note of which number you use.
5. If the Derby database server does not start correctly and you do not see a message similar to the above, then you will not be able to proceed. See the Apache Derby help site for information on troubleshooting your Derby installation
IS API Invoker Properties
Property | Default Value | Description |
|---|---|---|
SAP Hostname | localhost | DNS name or IP address of the destination SAP application server. |
SAP Router String | Security setting for access to the SAP system behind a firewall. Usually, this will be blank. | |
Language | en | Language for login to the destination SAP application server. |
System Number | 0 | System number for login to the destination SAP application server. |
Client Id | 100 | Client Id login for the destination SAP application server. |
Username | User name for login to the destination SAP application server. | |
Password | Password for login to the destination SAP application server. | |
Max Connections Allowed | 10 | Maximum number of concurrent connections for the connection pool. |
Connection Pool Size | 10 | Total number of available connections in the connection pool. |
Connection Expiration (seconds) | 60 | Length of time after which an idle connection expires. |
Expiration Check (seconds) | 3 | Frequency of checking for expired connections. |
Connection Time Out (seconds) | 30 | Length of time for waiting to establish a connection. |
Debug Folder | If specified, then the SAP XML representation of the current function module is saved to this location just prior to execution. |
Supported Actions
Action | Description |
|---|---|
Connect | Creates a database connection. |
Execute | Executes the supported action. |
Disconnect | Closes an existing database connection and performs clean up as needed. |
Supported Action Parameters
The IS API Invoker supports the following step action parameters for the Execute action.
Parameter | Supported Actions | Description |
|---|---|---|
Source Message | Execute | DNS name or IP address of the destination SAP application server. Source message is not required but can be used to pass in the PARAM_MAP message property, which overrides any corresponding parameter or structure values. The PARAM_MAP property takes the form of a Java properties file with the following syntax: • Simple Parameter: PARAM_NAME=PARAM_VALUE • Structure Field: STRUCT_NAME.FIELD_NAME=FIELD_VALUE Complete structures can also be mapped if they share the same fields: STRUCT_NAME=FUNCTION_NAME.STRUCT_NAME The second structure must already exist in the repository and be populated with data. Tip... To override multiple properties, use a CR+LF separator. Overriding Tables Tables cannot be overridden using PARAM_MAP. Instead, pass in CSV data using the Source Message property. A header is required, but double-quote delimiter characters are optional. The naming convention for table override of the Source Message property is LOAD_TABLE.TABLENAME. |
Target Message | Execute | Target message is not required but can be used to retrieve a proprietary XML representation of the function template or execution results. Target message properties are also automatically populated for any export parameters or structure fields that contain data. |
Supported Action Properties
Property | Supported Actions | Description |
|---|---|---|
RFC Function Name Search | Execute | Enter either simple text or a macro name to search the specified SAP server for the RFC function to execute. Only remotely enabled functions are returned. Search supports the asterisk << Image>> and percent sign (%) as wild card characters. Results are used to populate the RFC Function Name list (see below). The search must return fewer than 100 results. |
RFC Function Name | Execute | Name of the RFC module that you wish to execute. |
Repository Location | Execute | Location of the embedded or network server Derby instance used to store the RFC metadata and parameters. |
Repository Type | Execute | Embedded and client-based repositories are supported. Embedded repositories require no additional software. Client-based repositories require a running instance of the Derby network server. Client-based repositories are usually preferable at design time, and embedded repositories are preferable at run time. Macros used may change depending on the environment. |
Execute Operation | Execute | How the selected RFC is used at run time. Select one of the following options from the list: • Generate Template - Generates function metadata in the repository. • Execute Function - Executes the function using data stored within the repository and/or within the PARAM_MAP source message property. |
Write Response XML | Execute | When True, an XML representation of the RFC function results is returned in the body of the target message. |
Create Optional Templates | Execute | When True, all function metadata is generated in the repository. When False, only metadata required for execution is generated in the repository. Note: This option is only valid when the Execute operation is set to Generate Template. |
Return Empty Tables | Execute | When True, all function tables are generated in the repository. When False, only tables containing data are generated in the repository. This option is only valid when the Execute operation is set to Execute Function. |
Errors
Action | Description |
|---|---|
50 | Displayed for all run-time errors. |
999 | Displayed when the function executes correctly in SAP, but contains a RET_CODE parameter or RETURN structure with a code other than 0. |
Orchestration Invoker 1.0.0
The Orchestration Invoker runs Job Configurations that are stored and configured on Actian Integration Manager Server (version 1.3 or later). This invoker has several features for running Job Configurations synchronously or asynchronously by checking the status of a job or execution and retrieving the log of a completed execution.
Orchestration Invoker Properties
Property | Description |
|---|---|
Server | IP address or name of the server where Actian Integration Manager is installed. |
Port | Port number to connect to Actian Integration Manager (8080 by default). |
HTTP User Name | User name to connect to Actian Integration Manager. Note: It is recommended to have administrative permission to access the Job Configurations that you need to run. |
HTTP Password | Password to connect to Actian Integration Manager. |
Supported Actions
Action | Description |
|---|---|
Execute | Execute job configuration on Actian Integration Manager Server. |
Supported Action Parameter
Action | Parameter | Description |
|---|---|---|
Execute | Source Message | The function of the source message is based on the selected Execute action property: • If Run Config or Run Config and Wait is selected, then source message is not used. • If Check Status or Get Log is selected, then the optional source message can be the target message from Run Config to get the Log or to check the status of the respective execution. |
Execute | Target Message | The function of the target message is based on the selected Execute action property. For Run Job Config, the information about the submitted job is returned to the target message. • This message can be provided to a Get Log method or a Check Status method to get the log or status of that job. • If the method is Get Log or Run Job Config and Wait, then the target message contains the log body in the text message body. • If the method is Check Status, then the target message contains a property called status that has the status of the job. For example, the statuses are FINISHED_OK and FINISHED_ERROR. |
Supported Action Property
Action | Property | Description |
|---|---|---|
Execute | Method | Select one of the following options: • Run Config: Asynchronously submits a job for execution on Actian Integration Manager. • Get Log: Captures the log from a job configuration execution and adds the contents of the existing log in to the current process log. It also adds the contents of the job execution log to the body of the target message. • Get Status: Retrieve status of the job execution. • Run Config and Wait: Performs all the actions same as Run Config, Get Log, and Get Status. It submits a job configuration for execution, and continues to check the status until complete (or until timeout and retry limits have been reached) to return the log. |
Execute | Job Configuration (for Run Job Config and Wait only) | The Job Configuration ID that you want to run. This ID is available in Actian Integration Manager. Note: The integer ID of the Job Configuration is not the name of the Job Configuration. |
Execute | (Optional) Job Execution ID (For Get Log and Check Status methods only) | There are multiple ways to get the Log of an execution or to check the status of an execution. The easiest way is to use the target message from a Run Job Config method call. You can also maintain and track job executions through another method by adding a Job Execution ID to retrieve the log or status. |
Execute | Polling Timeout (s) (Run Config and Wait method only) | The Run Job Config and Wait method should poll the execution for completion status in seconds. |
Execute | Retry Count (Run Config and Wait method only) | Number of times the Run Job Config and Wait method can be run and check the status of an execution before stopping the execution and proceeding. |
Additional Information
The target messages from each method returns a list of executions in the order they were submitted. This is another option to check the overall status of all the submitted jobs. This list of executions are set in the target message Executions property as a comma delimited list.
Errors
Code | Description |
|---|---|
50 | Job Config or Execution not found |
Dynamic Map Invoker
Use Dynamic Map Invoker to load source data, target data, and maps into a message object at run time. For example, you can do any of the following by using a Scripting step:
• Load a map into a message object and use the message Uniform Resource Identifier (URI) as your source.
• Load a source file into a message object and use the message as your transformation source.
• Load the output of a transformation into a message object. Then retrieve the output from the message using the FileRead function.
Source and target connectors are exposed in a properties list and are configured as component options in the Properties tab. The Dynamic Map Invoker connection string supports authentication.
Supported Actions
Action | Description |
|---|---|
Execute | Runs an expression that you specify directly or through the invoker. |
Supported Action Parameters
Action | Property | Description |
|---|---|---|
Execute | SourceMessage | Type a name for the input message. |
TargetMessage | Type the name for the target message. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | Map URI | Uniform Resource Identifier name |
Source Connector | Type of source connector | |
Source Connection | Connection string containing path and properties/values | |
Target Connector | Type of target connector | |
Target Connection | Connection string containing path and properties/values | |
Output Mode | Output mode to use when executing the map. The default setting is the value stored in tf.xml file associated with the map. | |
Additional Mappings | (Optional) Path and name of XML file for mapping previously unmapped fields. |
Using Additional Mappings Property
The Additional Mappings property provides a method to map fields at run time that were not previously mapped in the .map file. The value for property is the path to a valid SimpleMap file. SimpleMap is an XML file with only one element, MapExpression.
The Additional Mappings property overrides mappings in the transformation named in the Map URI property.
• The expressions in the SimpleMap file overwrite those in the map named in the Map URI property.
• Any field you define in the SimpleMap file that is not in the map named in the Map URI property is added to the target schema at run time.
To use the Additional Mappings property, insert the path to the SimpleMap file as the value.
The following SimpleMap file adds an email field to the transformation:
<?xml version="1.0" encoding="UTF-8" ?>
<!--====== Map XML ======-->
<!-- <!DOCTYPE SimpleMap SYSTEM "DJSimpleMap.dtd"> -->
<SimpleMap schemaVersion = "1.0" version = "1.0" creator = "username" datecreated = "2007-02-15T19:58:13Z" author = "authorname" datemodified = "2007-02-15T19:58:13Z">
<MapExpression fieldname = "Email">Email</MapExpression>
</SimpleMap>
<!--====== Map XML ======-->
<!-- <!DOCTYPE SimpleMap SYSTEM "DJSimpleMap.dtd"> -->
<SimpleMap schemaVersion = "1.0" version = "1.0" creator = "username" datecreated = "2007-02-15T19:58:13Z" author = "authorname" datemodified = "2007-02-15T19:58:13Z">
<MapExpression fieldname = "Email">Email</MapExpression>
</SimpleMap>
Errors
The Dynamic Map Invoker component supports these error conditions.
Error Code | Error Name | Description | Reason |
|---|---|---|---|
4 | READERR | Error encountered while attempting to read a file. | Error reading a mapping file. |
8 | OPENERR | Error encountered while attempting to open a file. | Error opening a mapping file. |
SMTP Email Invoker
SMTP Email Invoker supports sending text and binary emails.
Email components support encoding in all character sets when email is sent and received. The message header and body are encoded in the character set specified by the MIME type. The email components support only Base64 and other MIME encoding. Enriched encoding is not supported.
Note: The SMTP Email Invoker component implicitly trust the certificates presented by the email servers that require SSL or TLS connections, regardless of the issuer.
SMTP Email Invoker Properties
Property | Description |
|---|---|
User Name | The username to connect to the SMTP mail server. A valid username is required if SMTP Authentication is set to TRUE and can be left blank if SMTP Authentication is set to FALSE (for anonymous login). |
Password | The password to authenticate the above username. A valid password is required if SMTP Authentication is set to TRUE and can be left blank if SMTP Authentication is set to FALSE (for anonymous login). |
Server Name | SMTP server name. |
Port | The port number. Default is 25. Note: If the default port is not used, then the component assumes a secure (SSL or TLS) connection.The port number for SSL is 465 and TLS is 587. |
ConnectionTimeOut | Connection time-out in seconds. The default is 90. |
Retry Count | Number of attempts the server tries to establish connection when connection times out or fails. Default is three attempts. |
From | Email address of sender. |
Reply-To | Email address for replies. |
To | Email address of the recipient. You can specify multiple recipients delimited with commas and no space between the comma and the next recipient. Also, you can right-click and select Paste Macro to specify multiple recipients in one macro. |
To List | Full path to a text file that contains email addresses (comma-separated). |
Subject | Subject of the message. |
Attachment | Document(s) attached with the email message. You can specify multiple attachments delimited with commas and no space between the comma and the next attachment. Also, you can right-click and select Paste Macro to specify multiple attachments in one macro. |
SMTP authentication | Specifies if mail server authentication is required. • TRUE (default) - If set to TRUE, the server requires a username and password for authentication. • FALSE - If set to FALSE, the username and password is left blank for anonymous login. |
Encoding String | Encoding string required for the email. Default is ISO-8859-1. |
Content Type | The content type for the email body: • text/plain • text/html • text/richtext |
Email Attachment
Both Email send and get components support attachments. For email sender (SMTP Invoker), attachment can be added to the djmessage or sent as file attachment in the Attachment option. For POP3 Queue or IMAP Queue, attachment is from djmessage. For information about the target djmessage attachment, see POP3 Email Queue and IMAP Email Queue.
Djmessage attachment has the following three properties:
• Content-Type: MIME type identifies the type of attachment content that is being sent, which is the same as email content-type. The following table provides the supported content types for email attachments using djmessage.
Content Type | Details |
|---|---|
text/* | • Text • HTML |
image/* | • .gif • .jpg |
application/* | All applicable file extensions such as .doc, .xls, and .zip. |
• Content-Transfer-Encoding: Defines encoding methods for transforming binary email message data into the US-ASCII plain text format. Content transfer encoding is defined in RFC 2045. Base64 encoding is the scheme used to transmit binary data.
• FileName: String containing the filename of the attachment.
Supported Actions
Action | Description |
|---|---|
Connect | Establishes a connection to a SMTP server, which is useful when you are testing your configuration. |
Execute | Executes the supported parameters and properties. |
Disconnect | Breaks the connection with an SMTP server which is useful when you need to disconnect before a process is complete. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Input message |
Errors
Errors are generated when email messages cannot be sent or received. Typical errors include the following:
• Connection time-out
• Unable to disconnect from the email server
• Errors while sending email messages
• Errors while receiving email messages
• Miscellaneous or unknown errors
All errors are written to an error log, which you can use to diagnose and troubleshoot the problem. Error messages specify whether a problem occurred while receiving or sending.
The error log also contains error codes that help you identify and understand the cause of the error. The following table describes error codes generated while sending or receiving email.
Code | Description |
|---|---|
19 | Unable to connect to the mail server |
27 | Unable to disconnect from the mail server |
8 | Unable to send email |
4 | Unable to receive email |
50 | Unknown error |
1 | End of File |
12 | No more messages to download |
0 | Messages sent or received successfully |
Example
The following process demonstrates how to send an email using the SMTP Email Invoker type of process step and receive email using the POP 3 Email Queue type of process step. In both SMTP Email Invoker and POP 3 Email Queue components, the Subject component property is a basic property for sending and retrieving emails. In this sample, a date variable is added to the value of "Subject" dynamically, so that the retrieved (get) emails are filtered by the sending the date contained in the Subject property.
DataConnect uses a djMessage object (srcmsg) to define properties of the SMTP type email, such as email body and attachment, and uses another djMessage object (trgmsg) to get properties of the retrieved email, such as email body and attachment, with accessing method of POP3 from the same email server. The maximum size limit for DJMessage is 512 MB.
See the following Set Attachment script for setting the email body and email attachment and the Get Attachment script for retrieving the email body and attachment.
The expression for Set Attachment script step:
set srcmsg = new djmessage "srcmsg"
set trgmsg =new djmessage("trgmsg")
srcmsg.body="EMail_GetAttachment_" & Date()
set attachmsg1 = new DJMessage "attachmsg1"
attachmsg1.body=fileread( MacroExpand("$(Fundamentals_Data_In)") & "/TUTOR1.ASC",ENC_ISO8859_1)
srcmsg.addAttachment(attachmsg1)
set attachmsg2 = new DJMessage "attachmsg2"
attachmsg2.properties("Content-Transfer-Encoding") = "base64"
attachmsg2.properties("Content-Type") = "application/vnd.ms-excel"
attachmsg2.body=B64Encode(fileread( MacroExpand("$(Fundamentals_Data_In)") & "/ExcelV4_TUTOR1.xls",ENC_ISO8859_1),ENC_ISO8859_1)
srcmsg.addAttachment(attachmsg2)
attachmsg2.properties("FileName") = "ExcelV4_TUTOR1.xls
The expression used for Get Attachment script step:
LogMessage("INFO","Source Count: " & srcmsg.attachmentCount())
LogMessage("INFO","Target Count: " & trgmsg.attachmentCount())
For i=0 to trgmsg.attachmentCount()-1
set msgAttach1 = trgmsg.getAttachment(i)
if strcomp(msgAttach1.properties("Content-Transfer-Encoding"),"base64",1)==0 then
decmsg=B64Decode(msgAttach1.body,ENC_ISO8859_1)
FileWrite("$(Fundamentals_Data_Out)/Email_Attachment1.XLS", decmsg,ENC_ISO8859_1)
else
decmsg=StrReplace(chr(13) & chr(10), chr(10),msgAttach1.body)
FileWrite("$(Fundamentals_Data_Out)/Email_Attachment2.TXT", decmsg,ENC_ISO8859_1)
end if
Next
FileWrite(MacroExpand("$(Fundamentals_Data_Out)") & "/Email_body.txt", trgmsg.body)
Query to WebRowSet Invoker
The Query to WebRowSet Invoker takes a query statement, queries a database, and writes the result to one or more WebRowSet files. The component creates an empty file named EOR.xml to signal the end of query records.
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the source message for the invoker. The body of the message must contain the query statement. The BatchSize message property specifies the number of records to write to a WebRowSet file. If this property is not set or has a negative value, only one WebRowSet file is generated and returned in the target message. If BatchSize has a positive value, the target message contains a BatchCount property that provides the number of WebRowSet files written to TargetDirectory. |
TargetMessage | Name of the target message for the invoker The content of the message depends on the BatchSize property value in the source message. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | SourceType | Source database type |
SourceServer | Source server host name | |
SourceDatabase | Source database to query | |
Username | User ID to access the source database. The connection is limited to the access rights of the user ID that you use. | |
Password | Password to access the source database | |
TargetDirectory | Directory where additional WebRowSet files, if any, are written |
Note: Any property value you set in the source message overrides the invoker property value.
REST API Invoker
This component implements the client side of HTTP protocol used as communication channel between many enterprise and distributed applications. It can be used to execute simple HTTP requests and to invoke REST and SOAP web services.
For information about the capabilities, see the following sections:
REST API Invoker 1.x
This topic provides information about REST API Invoker 1.1.0.
Rest API Invoker Properties
Property | Default Value | Description |
|---|---|---|
Protocol | HTTP | Select the secure and unsecure communication over SSL. Protocols supported are: • HTTP • HTTPS • HTTPS (Debug) HTTPS (Debug) allows SSL communication without a valid certificate. |
URL | Main endpoint used by current REST session. Space characters are automatically URL-encoded to "%20". | |
Send Source Via | BODY | Determines whether the Source DJMessage is sent in the HTTP body or appended to the URL and any specified URL query string (as a URL-encoded string). Multiple URL parameters may be set and encoded using source message properties (see Additional Notes). |
Message Encoding | UTF-8 | Text encoding to be used in the body of the source and target DJMessage objects. The options available are: • UTF-8 • ISO-8859-1 |
Content Type | text/xml; charset=UTF-8 | Content-Type header in the HTTP request. The options available are: • text/xml; charset=UTF-8 • text/xml; charset=ISO-8859-1 • application/x-www-form-urlencoded |
HTTP Username | User name when Basic, Digest, or NTLM authentication schemes are required. | |
HTTP Password | Password when Basic, Digest, or NTLM authentication schemes are required. | |
Domain (NTLM Only) | Domain when Windows NTLM authentication scheme is required. | |
Proxy Server | Host name or IP address of a proxy server. | |
Proxy Port | Port on which the proxy server is listening. | |
Proxy Username | User name for proxy server where required. If NTLM authentication scheme is required, then the Domain (NTLM Only) option must also be set. | |
Proxy Password | Password for proxy server, where required. | |
Truststore File | Truststore file | |
Truststore Pswd | Password to access the trustore file | |
SSL/TLS Version | Any | Determines the SSL context or the enabled protocol for SSL. This option is displayed only when the Protocol is set to HTTPS or HTTPS (Debug). The supported SSL and TLS protocols are: • Any • SSLv3 • TLSv1 • TLSv1.1 • TLSv1.2 If you select Any, the SSL/TLS protocol is decided by Apache http component and Java runtime. The default value is Any. Make sure that Java is installed to use these SSL and TLS version protocols. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported actions listed in Supported Action Properties. |
Disconnect | Closes an existing database connection and performs any clean up actions if required. |
Supported Action Parameters
Supported Actions | Parameter | Description |
|---|---|---|
Execute | Source Message | Body of HTTP request. |
Target Message | Body of HTTP request. |
Supported Action Properties
Supported Action | Property | Description |
|---|---|---|
Execute | HTTP Method | HTTP Method to be executed. See the HTTP 1.1 specification for additional details. Methods supported are: • POST • GET • HEAD • TRACE • OPTIONS • PUT • DELETE Default method is POST. Note: When using the POST method, the source message body is used as the body of the HTTP request. When using the PUT method, the source message body is assumed to be the URL of a file on the file system to use as the body of the request. |
Execute | URL Query String | Allows a query string or additional URL information to be appended to the URL. The URL is appended in the following manner: URL + URL Query String + URL-Encoded String. URL-Encoded String is taken from the Source Message when Send Source Via == URL. Any value used within this option is read literally and must already be URL-Encoded. Example using Send Source Via == URL URL: http://www.google.com/ Send Source Via: URL URL Query String: ?var= Source Message Text: "<test>Documents and Settings</test>" Example using Send Source Via == BODY URL: http://www.google.com Send Source Via: BODY URL Query String: ?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E" Resulting URL String in both Examples = "http://www.google.com/?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E" This option is ignored when one or more parameters are set with the Source Message Properties (see Additional Notes). |
Execute | SOAP Action | Sets the SOAPAction header in the HTTP request, when required. This value is only required when connecting to strongly typed web services. |
Execute | Connect Retry Count | Determines the number of retry attempts made when an exception occurs. There is a one second delay between retry attempts. If the value is negative, the retry attempt default is zero. Note: If the method to be executed is GET, HEAD, TRACE, or OPTIONS, then multiple retry attempts are made regardless of exception. However, if the method to be executed is POST, PUT, or DELETE, multiple retry attempts are only made when the following exceptions occur: • NoHttpResponseException • ConnectTimeoutException • UnknownHostException • ProtocolException • Connection is dropped before the request is fully sent to the server Default is five retry attempts. |
Execute | Connect Timeout (secs) | Determines the number of seconds to wait for a response once a socket connection is made. If the value is set to <= 0 seconds, then time-out defaults to 30 seconds. Note: If a socket connection cannot be established or is dropped, then this value has no effect. Default is 30. |
Execute | Log HTTP Headers | When set to true, all HTTP request and response headers are written to process log file. Default is true. |
Execute | Write Response File | Click Browse and specify the file path. The response is written directly to the file, and not to the target message body. When no file path is specified, response text is placed in the target message body. Use this option in the following situations: • The response is known to be very large. • The response may have invalid characters for the specified encoding scheme. |
Error Conditions
The REST API Invoker has the following error conditions.
Error Code | Description |
|---|---|
50 | Displayed for all run-time errors. |
HTTP Status Code | Error Code = HTTP Status Code for all Status Codes >= 400 Error Code = 0 for all other Status Codes (including 200 OK), as Status Codes below 400 may be expected and/or desirable for certain requests. Refer to the HTTP 1.1 specification for additional information regarding HTTP Status Codes. |
Limitations
The REST API Invoker has the following limitations:
• Kerberos authentication schemes are not currently supported.
• Multipart POST and MIME attachments are not currently supported.
Use Case - Managing Multiple URL Parameters
This component automatically scans for source message property names which begin with "P." or deprecated "_". If any exist, these properties are converted and encoded as URL parameters without the "P.". If Send Source Via == URL, then the source message body is ignored. If any URL Query Strings are present within the step, they are also ignored.
Example:
SourceMessage.Properties("P.var") = "<test>Documents and Settings</test>"
SourceMessage.Properties("P.var2") = "&&&&"
SourceMessage.Properties("P.var3") = "<<>>"
URL: http://www.google.com/
Resulting URL String = "http://www.google.com/?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E&var2=%26%26%26%26&var3=%3C%3C%3E%3E"
SourceMessage.Properties("P.var2") = "&&&&"
SourceMessage.Properties("P.var3") = "<<>>"
URL: http://www.google.com/
Resulting URL String = "http://www.google.com/?var=%3Ctest%3EDocuments%20and%20Settings%3C%2Ftest%3E&var2=%26%26%26%26&var3=%3C%3C%3E%3E"
Additional Notes
Managing Session Cookies
This component automatically manages a single session cookie across invoker steps within a single invoker session.
In some cases it may be necessary to force a cookie value or to share a cookie across multiple invoker sessions or even subprocesses. Once a session is established, the cookie value can be retrieved using TargetMessage.Properties("Cookie"). This value can then be used to manually set or override the cookie for any invoker step using SourceMessage.Properties("Cookie"), regardless of the parent session of the step.
Managing HTTP Headers
This component automatically scans for Source message Property Names which begin with "H.". If any exist, these properties create or override existing HTTP request headers.
SourceMessage.Properties("H.Content-Type") = "text/plain"
SourceMessage.Properties("H.CustomHeader") = "Some Value"
This code adds the following to the header:
Content-Type: text/plain
CustomHeader: Some Value
CustomHeader: Some Value
REST API Invoker 2.x
In addition to the capabilities available in REST API Invoker 1.x, REST API Invoker 2.3.0 supports the following additional features:
• NTLM v2 authentication
• Multipart post requests
• Binary attachments with and without base 64 encoding
In REST API Invoker 2.3.0, the response headers are available as properties of the target DJMessage, if specified.
This section provides information about the following:
• Errors
Supported Scenarios
The REST API Invoker supports the following scenarios.
• Non-secure connection to a server: In this case, there is no need to configure a truststore or keystore.
• Server uses a certificate that is either self-signed or signed by an unknown certificate authority (CA): In this case, you must download the self-signed certificate or the unknown CA to the local system and do one of the following:
– Install the self-signed certificate or unknown CA into the lib/security/cacerts file of the JRE. In this case, the REST API Invoker configuration is not required.
– Install the self-signed certificate or unknown CA into a custom truststore (a Java keystore file that will be used specifically to determine the trustworthiness of the server) and configure the REST API Invoker to use the custom truststore.
• Server requires that the client present a certificate that is self-signed or signed by a custom CA: In this case, the client must install the certificate or certificate chain into a local java keystore and configure the REST API Invoker to provide it to the server when requested (during initial SSL handshake).
REST API Invoker 2.x Properties
Property | Default Value | Description |
|---|---|---|
Protocol | HTTP | Supports secure and unsecure communication over SSL. Protocols supported are • HTTP • HTTPS • HTTPS (Debug) HTTPS requires the use of a trust store. HTTPS (Debug) allows SSL communication without the use of a valid certificate by trusting all certificates. |
URL | The endpoint of the current REST API session. Include the port number if required. The format is <protocol>://<domain name>:<port number>/resource path. For example: http://www.mywebservice.com:80/Specific/API/URL Make sure the URL is encoded properly before adding the value for this property. Contact the administrator of your Web service endpoint if you are not sure of the encoding that is required. | |
Send Source Via | BODY | Specifies whether the source DJMessage is sent in the HTTP body or appended to the URL and any URL query string (as a URL-encoded string) that has been specified. You can set and encode multiple URL parameters using source message properties (see Additional Notes). |
Message Encoding | UTF-8 | The text encoding to use in the body of the source and target DJMessage objects: UTF-8 or ISO-8859-1. |
Use Base64 Encoding | No | When sending a binary attachment, indicates whether the attachment must be encoded in base 64 before being sent. |
Content Type | text/xml | The content type for the header of an HTTP request. Supported types: • text/xml • text/html • text/plain • application/json • application/x-www-form-urlencoded • application/xml • multipart/form-data • application/atom+xml • application/octet-stream • application/svg+xml • application/xhtml+xml • wildcard |
HTTP Username | The user name when Basic, Digest, or NTLM authentication schemes are required. | |
HTTP Password | The password when Basic, Digest, or NTLM authentication schemes are required. | |
Domain (NTLM Only) | The domain when Windows NTLM authentication scheme is required. | |
Proxy Server | The host name or IP address of the proxy server. | |
Proxy Port | The port on which the proxy server is listening. | |
Proxy Username | The user name for the proxy server, where required. If an NTLM authentication scheme is required, you must also set the Domain (NTLM Only) option. | |
Proxy Password | The password for the proxy server, where required. | |
Keystore File | The keystore file that the REST API Invoker must provide to the server during initial SSL handshake. This property appears only when the Protocol property is set to HTTPS. Note: The certificate or the certificate chain must be installed into a local java keystore. | |
Keystore Pswd | The keystore password for the keystore file. This property appears only when the Protocol property is set to HTTPS. | |
Truststore File | The full path to the trust store certificate from the keystore location. This property appears only when the Protocol property is set to HTTPS. | |
Truststore Pswd | The password to access the specified trust store. This property appears only when the Protocol property is set to HTTPS. | |
SSL/TLS Version | Any | Determines the SSL context or the enabled protocol for SSL. This option is displayed only when the Protocol is set to HTTPS or HTTPS (Debug). The supported SSL and TLS protocols are: • Any • SSLv3 • TLSv1 • TLSv1.1 • TLSv1.2 If you select Any, the SSL/TLS protocol is decided by Apache http component and Java runtime. The default value is Any. Make sure that Java 8 LTS is installed to use these SSL and TLS version protocols. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the actions listed in Supported Action Properties. |
Disconnect | Closes an existing database connection and performs any cleanup actions if required. |
Supported Action Parameters
Action | Property | Description |
Execute | SourceMessage | Body of the HTTP request. |
Execute | TargetMessage | Body of the HTTP request. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | HTTP Method | HTTP Method to be executed. Default method is POST. Supported methods: • POST • GET • HEAD • TRACE • OPTIONS • PUT • DELETE • PATCH See the HTTP 1.1 specification for additional details. |
Execute | URL Query String | Allows a query string or additional URL information to be appended to the URL. The URL is appended in the following manner: URL + URL Query String + URL-Encoded String. The string will be URL encoded in the following MIME format: application/x-www-form-urlencoded |
Execute | SOAP Action | Sets the SOAPAction header in the HTTP request, when required. This value is required only when connecting to strongly typed web services. |
Execute | Connect Retry Count | The number of retry attempts to make when an exception occurs. If the value is negative, the retry attempt default is zero. The Connect Retry Delay property value is used between retry events. Note: If the method to be executed is GET, HEAD, TRACE, or OPTIONS, multiple retry attempts are made regardless of any exceptions. If the method to be executed is POST, PUT, or DELETE, multiple retry attempts are made only when the following exceptions occur: • NoHttpResponseException • ConnectTimeoutException • UnknownHostException • ProtocolException Connection is dropped before the request is fully sent to the server Default is 5. |
Execute | Connect Retry Delay (ms) | The time (in milliseconds) to wait between retry attempts. The default value is 1000. |
Execute | Log HTTP Headers | When set to true, all HTTP request and response headers are written to a process log file. Default is True. |
Execute | Read Source File | The file that is to be upload. |
Execute | Read Source Folder | For multipart post requests, specify the folder location that contains the file that is to be uploaded. By default, all of the files in the specified folder are added to the request. To request specific files, you can add the following to a Script step before the invoker is called: requestMsg.properties("F.<filename>") = "<filepath>" You must add this line for each file you specify. See Multipart Post Options for more information. |
Execute | Write Response File | If a file name is not specified, response text is placed in the target message body. If the file name is specified, the response is written directly to the file instead of the target message body. Use this option in the following situations: • The response is known to be very large. • The response may have invalid characters for the specified encoding scheme. |
Execute | Write Response Folder | If a file path is not specified, response text is placed in the target message body. If the file path is specified, a response is written directly to the file instead of the target message body. Use this option in the following situations: • The response is known to be very large. • The response may have invalid characters for the specified encoding scheme. |
DJMessage Options
Custom Headers
Any REST API Invoker 2.2.0 call can contain custom headers that are specific to the web service being accessed. To add a custom header, add the following script to the source DJMessage:
srcMsg.properties("H.<HeaderName>") = "<Header Value>"
For example, a specific call might require a header called Authorization that takes a token for its value. This call might look like the following:
srcMsg.properties("Authorization") = "09bf14tzrw426b71fx6adfad12"
Multipart Post Options
When making multipart post requests, you must customize the following options for your request:
Specify a File to Send
You can specify a request folder and file name. The <FileName> is relative to the folder that is specified and the name of the file, including the extension.
srcMsg.properties("F.<FileName>") = "<FilePath>"
Specify the Content-Type of a File
By default, each file in a multipart post request uses the global content-type (the Content Type you set for the invoker). However, it is possible that some of the files you send will have a different content-type. To specify a different content-type for a specific file, use the syntax below. The file name should include the file extension.
srcMsg.properties("C.<FileName>" ) = "<content-type>"
Specify the Name Field of the Content-Disposition Header for a File
Certain web services may require the name field of the content-disposition header to have a certain value in order to successfully upload a file.
For example, a web service may expect a content-disposition header of the following form:
Content-Disposition: attachment; filename="accounts.csv"; name="spreadsheet"
By default, the name field is set to file for each file in the multipart post. If a file in a multipart post requires a specific name, you can specify the correct name using the following syntax:
srcMsg.properties("N.<FileName>") = "<content disp.name>"
Errors
You may encounter errors when you run your process. The following table shows messages error codes and their descriptions.
Code | Name | Description | Possible Reason |
|---|---|---|---|
0 | OK | No error. Used for all informational messages. | |
50 | UNSPECIFIED | An unexpected error occurred. Displayed for all run-time errors. | |
4 | READ ERROR | A file, input stream, or web service response could not be read. | |
27 | CLOSE ERROR | A file or input stream could not be closed. | |
20 | BAD FILE TYPE | The specified directory or file does not exist. | |
11 | RECORD TOO BIG | A file or input stream is too large to be read by the invoker (the maximum size is 2147483647 characters). | |
34 | INVALID | An option is invalid. | The invoker was redirected to an invalid location. For example, no location header was specified. |
44 | NOT SUPPORTED | An option is not specified. | The invoker could not encode a binary attachment to base 64 due to a charset error. |
REST API Invoker 3.x
In addition to the capabilities available in REST API Invoker 2.x, REST API Invoker 3.0.0 supports the following additional features:
• Support for RESTClient tool that facilitates interactive testing of an HTTP resource. This reduces the need to use external tools such as SoapUI to test the HTTP resource.
• Support for OAuth2 authorization code grant type.
• Session-level options such as URL, Send Source Via, and Content Type are moved to the step-level options so that the same instance of the REST API Invoker can be used in multiple steps.
This section provides information about the following:
• Errors
Supported Scenarios
The REST API Invoker 3.x supports the following scenarios:
• Non-secure connection to a server: In this case, there is no need to configure a truststore or keystore.
• Server uses a certificate that is either self-signed or signed by an unknown certificate authority (CA): In this case, you must download the self-signed certificate or the unknown CA to the local system and do one of the following:
– Install the self-signed certificate or unknown CA into the lib/security/cacerts file of the JRE. In this case, the REST API Invoker configuration is not required.
– Install the self-signed certificate or unknown CA into a custom truststore (a Java keystore file that will be used specifically to determine the trustworthiness of the server) and configure the REST API Invoker to use the custom truststore.
• Server requires that the client present a certificate that is self-signed or signed by a custom CA. In this case, the client must install the certificate or certificate chain into a local java keystore and configure the REST API Invoker to provide it to the server when requested (during initial SSL handshake).
REST API Invoker 3.x Properties
Property | Default Value | Description |
|---|---|---|
Protocol | HTTP | Supports secure and unsecure communication over SSL. Protocols supported are • HTTP • HTTPS • HTTPS (Debug) HTTPS requires the use of a trust store. HTTPS (Debug) allows SSL communication without the use of a valid certificate by trusting all certificates. |
Authentication | None | Supported server Authentication: • BASIC • DIGEST • NTLM • OAuth2 Bearer |
Message Encoding | UTF-8 | The text encoding to use in the body of the source and target DJMessage objects: UTF-8 or ISO-8859-1. |
Use Base64 Encoding | No | When sending a binary attachment, indicates whether the attachment must be encoded in base 64 before being sent. |
HTTP Username | The user name when Basic, Digest, or NTLM authentication schemes are required. | |
HTTP Password | The password when Basic, Digest, or NTLM authentication schemes are required. | |
Domain | The domain when Windows NTLM authentication scheme is required. | |
Bearer Token | The Bearer Token when OAuth2 Bearer authentication scheme is required. | |
Proxy Server | The host name or IP address of the proxy server. | |
Proxy Port | The port on which the proxy server is listening. | |
Proxy Username | The user name for the proxy server, where required. If an NTLM authentication scheme is required, you must also set the Domain (NTLM Only) option. | |
Proxy Password | The password for the proxy server, where required. | |
Keystore File | The keystore file that the REST API Invoker must provide to the server during initial SSL handshake. This property appears only when the Protocol property is set to HTTPS. Note: The certificate or the certificate chain must be installed into a local java keystore. | |
Keystore Pswd | The keystore password for the keystore file. This property appears only when the Protocol property is set to HTTPS. | |
Truststore File | The full path to the trust store certificate from the keystore location. This property appears only when the Protocol property is set to HTTPS. | |
Truststore Pswd | The password to access the specified trust store. This property appears only when the Protocol property is set to HTTPS. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported actions listed in Supported Action Properties. |
Disconnect | Closes an existing database connection and performs any clean up actions if required. |
Supported Action Parameters
Action | Property | Description |
Execute | SourceMessage | Body of the HTTP request. |
Execute | TargetMessage | Body of the HTTP request. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | Design | Click within the field and then click  to open the Rest API Invoker 3 Configuration window.After configuring the values in this tool, the result string appears in the textbox as the value. To change this value, you must click  .For more information, see Using Rest API Invoker 3.x Configuration Tool. |
Execute | HTTP Method | HTTP Method to be executed. Default method is POST. Supported methods: • POST • GET • HEAD • TRACE • OPTIONS • PUT • DELETE • PATCH See the HTTP 1.1 specification for additional details. |
Execute | URL | The endpoint of the current REST session. |
Execute | URL Query String | The endpoint of the current REST session. Include the port number if required. The format is <protocol>://<domain name>:<port number>/resource path. For example: http://www.mywebservice.com:80/Specific/API/URL Make sure the URL is encoded properly before adding the value for this property. Contact the administrator of your Web service endpoint if you are not sure of the encoding that is required. |
Execute | Headers | HTTP request headers. Formats: key1:value1;key2:value20;key2:value21 ..... At run-time, the input message can define message properties start with 'H.' for header. |
Execute | Cookies | HTTP cookie. Formats: key1=value1;key2=value2 ..... At run-time, the input message can define message properties 'Cookie'. |
Execute | Send Source Via | Specifies whether the source DJMessage is sent in the HTTP body or appended to the URL and any URL query string (as a URL-encoded string) that has been specified. The options are: • BODY • URL The default value is BODY |
Execute | Content Type | The content type for the header of an HTTP request. The options are: • text/xml • text/html • text/plain • application/json • application/x-www-form-urlencoded • application/xml • multipart/form-data • application/atom+xml • application/octet-stream • application/svg+xml • application/xhtml+xml • wildcard The default value is text/xml. |
Execute | SOAP Action | Sets the SOAPAction header in the HTTP request, when required. This value is required only when connecting to strongly typed web services. |
Execute | Connect Retry Count | The number of retry attempts to make when an exception occurs. If the value is negative, the retry attempt default is zero. The Connect Retry Delay property value is used between retry events. Note: If the method to be executed is GET, HEAD, TRACE, or OPTIONS, multiple retry attempts are made regardless of any exceptions. If the method to be executed is POST, PUT, or DELETE, multiple retry attempts are made only when the following exceptions occur: • NoHttpResponseException • ConnectTimeoutException • UnknownHostException • ProtocolException • Connection is dropped before the request is fully sent to the server Default is 5. |
Execute | Connect Retry Delay (ms) | The time (in milliseconds) to wait between retry attempts. The default value is 1000. |
Execute | Log HTTP Headers | When set to true, all HTTP request and response headers are written to a process log file. Default is True. |
Execute | Read Source File | The file that is to be upload. |
Execute | Read Source Folder | For multipart post requests, specify the folder location that contains the file that is to be uploaded. By default, all of the files in the specified folder are added to the request. To request specific files, you can add the following to a Script step before the invoker is called: requestMsg.properties("F.<filename>") = "<filepath>" You must add this line for each file you specify. See Multipart Post Options for more information. |
Execute | Write Source File | Write the HTTP request to the specified file. If not provided, the content of the source DJMessage will not be copied to a file |
Execute | Write Response File | Write the HTTP response to the specified file. If not provided, the response is written to the target DJMessage. |
DJMessage Options
Custom Headers
Any REST API Invoker 2.2.0 call can contain custom headers that are specific to the web service being accessed. To add a custom header, add the following script to the source DJMessage:
srcMsg.properties("H.<HeaderName>") = "<Header Value>"
For example, a specific call might require a header called Authorization that takes a token for its value. This call might look like the following:
srcMsg.properties("Authorization") = "09bf14tzrw426b71fx6adfad12"
Multipart Post Options
When making multipart post requests, you must customize the following options for your request:
Specify a File to Send
You can specify a request folder and file name. The <FileName> is relative to the folder that is specified and the name of the file, including the extension.
srcMsg.properties("F.<FileName>") = "<FilePath>"
Specify the Content-Type of a File
By default, each file in a multipart post request uses the global content-type (the Content Type you set for the invoker). However, it is possible that some of the files you send will have a different content-type. To specify a different content-type for a specific file, use the syntax below. The file name should include the file extension.
srcMsg.properties("C.<FileName>" ) = "<content-type>"
Specify the Name Field of the Content-Disposition Header for a File
Certain web services may require the name field of the content-disposition header to have a certain value in order to successfully upload a file.
For example, a web service may expect a content-disposition header of the following form:
Content-Disposition: attachment; filename="accounts.csv"; name="spreadsheet"
By default, the name field is set to file for each file in the multipart post. If a file in a multipart post requires a specific name, you can specify the correct name using the following syntax:
srcMsg.properties("N.<FileName>") = "<content disp.name>"
Using Rest API Invoker 3.x Configuration Tool
The Rest API Invoker 3.x Configuration tool facilitates interactive testing of the target HTTP resource.
The following features are supported:
• Specifying the target URL
• Setting the following:
– Request method
– Request headers
– Cookies
– Request body
• Setting or configuring authentication
• SSL configuration, including specifying the keystore and truststore
• Viewing or collecting the following:
– Response headers
– Response cookies
– Response body
• Formatted viewing of specific response content types
– text/xml
– application/xml
– application/json
After configuring values in this tool, the new values are applied to the component’s options and the component responds by updating all the applicable option values before returning.
For more information about this tool, in the Rest API Invoker 3 Configuration window, click Help > RESTClient Kindle and read the documentation.
Errors
You may encounter errors when you run your process. The following table shows messages error codes and their descriptions.
Code | Name | Description | Possible Reason |
|---|---|---|---|
0 | OK | No error. Used for all informational messages. | - |
50 | UNSPECIFIED | An unexpected error occurred. Displayed for all run-time errors. | - |
4 | READ ERROR | A file, input stream, or web service response could not be read. | - |
27 | CLOSE ERROR | A file or input stream could not be closed. | - |
20 | BAD FILE TYPE | The specified directory or file does not exist. | - |
11 | RECORD TOO BIG | A file or input stream is too large to be read by the invoker (the maximum size is 2147483647 characters). | - |
34 | INVALID | An option is invalid. | The invoker was redirected to an invalid location. For example, no location header was specified. |
44 | NOT SUPPORTED | An option is not specified. | The invoker could not encode a binary attachment to base 64 due to a charset error. |
Salesforce Login Invoker
Salesforce Login Invoker uses the Salesforce login API call to log in to salesforce.com with user name, password, and endpoint address properties as inputs. It then returns the session ID and server URL as properties in the target message object.
You can use the sessionID and serverURL to construct a session token, which allows you to connect to salesforce.com multiple times without having to log in repeatedly. You can also use the session token with the Salesforce.com connector. For information on how to set up and use session tokens, see the Salesforce connector section.
You should be familiar with Salesforce.com Web services before using this component.
Note: The Salesforce Login invoker is SHA-256 compliant.
The following versions of the invoker are available:
• Salesforce Login Invoker for version 8.0 WSDL or earlier
• Salesforce 10.0 Login Invoker for the 10.0 (Summer '07) WSDL
• Salesforce Login Invoker version 3.0 supports Salesforce API version 42.0
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the Source message for the invoker |
TargetMessage | Name of the Target message for the invoker |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | SourceMessage | Name of the Source message for the invoker |
Password | Password to access salesforce.com. | |
Endpoint Address | Address for salesforce.com endpoint. If you do not set this option, the invoker uses the default. The default setting is based on the WSDL version. You can change the number in the URL to any supported version, including versions 2.5 through 16. The default value is https://www.salesforce.com/services/Soap/u/16.0 When you call this option, use Endpoint, as shown in this example: sourceMsg.properties(“EndpointAddress”) = "https://www.salesforce.com/services/Soap/u/7.0" |
All invoker property values can be specified as properties in the Source Message, and those properties override any invoker property values.
For example, assume you have a Script step before the invoker that contains the following:
sourceMsg.properties("EndpointAddress") = "https://www.salesforce.com/services/Soap/u/10.0"
The sourceMsg in the Script step is used as the endpoint address for the invoker. No matter what value is specified in the EndpointAddress invoker property, the sourceMsg property is used as the endpoint address.
Errors
If the invoker encounters a problem while performing tasks, it displays an error message describing the failure. The following table describes some of the more common errors.
Code | Name | Description | Possible Reason |
|---|---|---|---|
46 | LICENSING | A valid product license is not found. | You must have a valid license tor this component in order to use it. |
34 | INVALID | The invoker could not log in to Salesforce.com. | The user name or password may be incorrect or the server may be unavailable. For more information, see the process log. |
50 | UNSPECIFIED | An unknown error occurred while loading the component. | For more information, see the process log. |
Salesforce Changed Data Query Invoker
Salesforce Changed Data Query Invoker calls query methods and outputs results into an XML file. The query methods, GetDeleted and GetUpdated, return a list of salesforce.com IDs that have been deleted or updated within a specified time period. The GetDeleted method also returns dates, such as when a particular ID was deleted.
You should be familiar with the salesforce.com web services before using this invoker.
The following versions of the invoker are available:
• Salesforce Changed Data Query Invoker supports version 8.0 WSDL or earlier
• Salesforce 10.0 Changed Data Query Invoker supports version 10.0 (Summer '07) WSDL
• Salesforce Changed Data Query Invoker 3.0 supports Salesforce API version 42.0
Note: The Salesforce Changed Data Query invoker is SHA-256 compliant.
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the Source message for the invoker |
TargetMessage | Name of the Target message for the invoker |
Supported Action Properties
Action | Name | Description |
|---|---|---|
Execute | User Name | User ID to access salesforce.com. The connection is limited to the access rights of the user ID that you use. For most purposes, enter a user ID with an Administrator profile. |
Execute | Password | Password to access salesforce.com |
Execute | Endpoint Address | Address for the salesforce.com endpoint. If you do not set this option, the invoker uses the default URL, which is based on the WSDL version. You can change the URL to connect to any supported version, including versions 2.5 through 16. When you call this option, use EndpointAddress as shown in this example: sourceMsg.properties("EndpointAddress") = "https://www.salesforce.com/services/use/u/10.0" To connect to a sandbox, use this example: sourceMsg.properties("EndpointAddress") = "https://test.salesforce.com/services/Soap/u/10.0" |
Execute | Method | Methods supported by the invoker: • GetUpdated - Retrieves a list of IDs that have been added or changed within a given time period for the specified object type. • GetDeleted - Retrieves a list of IDs that have been deleted within a given time period for the specified object type. The time period for the method is specified as the Start Date and End Date. |
Execute | Object Type | Name of the Salesforce entity to query. |
Execute | Start Date | Start date for the GetUpdated or GetDeleted methods in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ Example: 2006-12-20T12:09:15.000Z This option is required; null values cause an error to be returned. Note: The Start Date value cannot be more than 30 days in the past. |
Execute | End Date | End date for the GetUpdated or GetDeleted methods in the following format: yyyy-MM-ddTHH:mm:ss.SSSZ Example: 2006-12-25T06:00:45.000Z Caution! This option is required; null values cause an error to be returned. |
All invoker property values can be specified as properties in the Source Message, and those properties override any invoker property values.
For example, you may have a Script step before the invoker that does the following:
sourceMsg.properties("StartDate") = "2006-12-20T16:40:00.000Z"
The sourceMsg in the Script Step is used as the Source Message for the invoker, so no matter what is specified in the Start Date invoker property, the sourceMsg property value is used as the Start Date.
Errors
You may encounter errors when you run your process. See the following table for error codes and their descriptions.
Code | Name | Description | Possible Reason |
|---|---|---|---|
5 | NOMEM | The allocated Java heap space memory has been exhausted. | You need to increase the Java heap space memory allocation, or select dates that are closer together so that fewer records are returned. |
19 | OPENERR | Salesforce.com returned an EXCEEDED_ID_LIMIT or OPERATION_TOO_LARGE exception. | The start and end dates may return too many records. Select dates that are closer together so that fewer records are returned. |
33 | BADOPTIONVALUE | The component detected an invalid or missing property value. | You specified a value using an incorrect format or did not supply a value. |
34 | INVALID | The invoker could not log in to Salesforce.com. | User name or password may be incorrect. |
46 | LICENSING | A valid product license is not found. | You must have a valid license for this component in order to use it. |
50 | UNSPECIFIED | An error occurred while loading the component. | See the process log for more information. |
Salesforce Bulk Loader
The Salesforce Bulk API allows you to insert, update, upsert large numbers of records asynchronously. To do this, you must send a number of batches to the server using an HTTP POST call and the server processes the batches in the background. While batches are being processed, you can track the progress by checking the status of the job using an HTTP GET call. All operations use POST methods to send and receive XML or CSV data.
The Salesforce Bulk Loader supports only CSV data.
The Salesforce Bulk Load invoker is SHA-256 compliant.
Salesforce Bulk Loader Properties
Property | Description |
|---|---|
Username | User ID to access salesforce.com. The connection is limited to the access rights of the user ID that you use. For most purposes, enter a user ID with an Administrator profile. |
Password | Password to access salesforce.com. |
ProxyServer | Address of the proxy server, if it is required. |
ProxyAuth | Authentication string to be passed to the proxy server, if it is being used. |
APIVersion | The version of the Salesforce API. The default is 17. For Salesforce Bulk Loader version 2.0, specify the Salesforce API version as 42.0. |
Endpoint | Address for the salesforce.com endpoint (for the regular API). The default is https://www.salesforce.com/services/Soap/u/17.0. Note: The actual API endpoint used for the Salesforce Bulk API is slightly different, but the invoker determines the correct endpoint to use based on the regular API endpoint entered here. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the source message for the invoker |
TargetMessage | Name of the target message for the invoker |
Supported Action Properties
Action | Property | Default Value | Description |
|---|---|---|---|
Execute | sObject | Account | Name of the Salesforce entity (sObject is the internal name for entity). |
Execute | SourceCSV | Account.csv | The name of the CSV file to load into Salesforce. The default value must be changed. |
Execute | BatchSize | 10,000 | The number of records to send in each batch. The default value is . |
Execute | Operation | Insert | Select any of the following: Insert Update Upsert |
Execute | ExtIdField | The External ID field. This value is not used when the operation is 'insert', but is required for 'update' or 'upsert' operations. | |
Execute | SuccessFile | Account_Success.csv | Name of the file used to record successful record operations. Each successful record operation will contain the job ID, batch ID, record ID, and a flag indicating whether a new record was created. |
Execute | FailureFile | Account_Failure.csv | Name of the file used to record failed record operations. Each failed record operation will contain the job ID, batch ID, and a description of the error. |
Example
This example shows how to set properties for a new Salesforce Bulk Loader 1.0.0 invoker.
1. Enter a Username and Password for connecting to Salesforce.com.
The APIVersion and Endpoint fields are displayed by default. Modify them as necessary.
2. Select the source CSV file, and enter the correct name for the success and failure files.
3. Select the Action as Execute.
4. Click OK.
Note: For information on how to create the CSV source file, see the the Salesforce Bulk API documentation.
JDBC Stored Procedure Invoker
The JDBC Stored Procedure Invoker connects to a target database, runs the specified stored procedure, and returns either an XML file or WebRowSet data in the format of a response schema.
To use this invoker, you must have the following:
• Database experience
• Java Database Connectivity (JDBC) knowledge
• Scripting knowledge
• XML knowledge
The main features of the JDBC Stored Procedure Invoker are as follows:
• Supports any database with type 4 drivers only
• Executes the selected stored procedure on the database
• Returns an XML instance containing information on the stored procedure that was run, including all input and output parameters. In addition, it returns all result sets from the stored procedure.
To connect to a database using the JDBC Stored Procedure Invoker, you must have information about the repository home, database connection, and required type 4 JDBC drivers. The relevant type 4 JDBC-compliant driver .jar files must be on your computer. For example, if you are using Oracle9i, you must have the ojdbc14.jar file present on your computer.
This section provides information about the following:
• Errors
Design-Time Behavior
The JDBC Stored Procedure Invoker performs the following during design-time:
1. When the procedure or optional package information is selected in the step properties, the component reads the connection information, loads the drivers, and connects to the target database using the host URL, with a user ID and password.
2. Parses the request XML file to check for occurrences of the <ServiceInfo> tag.
3. Component does one the following:
• If the request XML file contains the tag, then the JDBC Stored Procedure Invoker uses the connection information specified within the tag to connect to the database.
• If the request XML file does not contain the tag, then the JDBC Stored Procedure Invoker uses the information specified in the instance properties (drivers, JAR location, and so on) to connect to the database.
4. Component connects to the target database.
5. Displays the stored procedures in the database based on the search criteria.
6. Invoker creates the request and response schema for the selected stored procedure in the repository home folder.
7. Disconnects from the target database.
Note: The request and response schemas are used only at design-time and not at run-time.
Run-Time Behavior
JDBC Stored Procedure Invoker performs the following during run-time:
1. Reads the connection information, loads the drivers, and connects to the target database using the Host URL, User ID, and password.
2. Parses the request XML file to check for occurrences of the <ServiceInfo> tag.
3. JDBC Stored Procedure Invoker does one the following:
• If the request XML file contains the tag, then JDBC Stored Procedure Invoker uses the connection information specified within the tag to connect to the database.
• If the request XML file does not contain the tag, then JDBC Stored Procedure Invoker uses the information specified in the instance properties (drivers, .jar file location, and so on) to connect to the database.
4. Connects to the target database.
5. Optional: Starts a transaction based on steps used in the process.
6. Executes the selected stored procedure.
7. Returns the data in the format of a response schema containing information on the stored procedure.
8. Optional: If a transaction was started, performs rollback or commit.
9. Disconnects from the target database.
Note: The request and response schemas are used at design time only, not at run time.
Procedure Schema
This parameter narrows the search for stored procedures in the database schema.
• If this parameter is empty, all procedures from all schemas are returned.
• If this parameter contains a valid value, only procedures in the named schema are returned.
The step property Stored Procedure contains the schema name. The database returns schema.procedure.
DB2 Limitations
The client and server version must be compatible.
Version Mismatch Errors
The following errors indicate a DB2 version mismatch:
DB2 SQL error: SQLCODE: -1109, SQLSTATE: , SQLERRMC: SYSIBM.
SQL0805N Package "NULLID.SYSSH200"
Not found SQLSTATE=51002.
SQL0805N Package "NULLID.SYSSH200"
Not found SQLSTATE=51002.
Understanding a Request XML
Before you can use the JDBC Stored Procedure Invoker, you must understand how the request schema relates to the XML instance passed into the component at run time.
The schema defines the elements and attributes in the XML request and is generated based on the metadata from the procedure. The procedure parameter names become the element names and the properties of the parameters become the attributes.
The following example shows the pertinent portions of a request schema for an Oracle procedure with input of a number and REF CURSOR output:
<xsd:element name="ACNO" type="ACNO Type"/>
<xsd:element name="CV" type="CV_Type"/><xsd:choice>
<xsd:complexType name="ACNO_Type">
<xsd:simpleContent>
<xsd:extension base="xsd:integer">
<xsd:attribute name="Direction" fixed="IN"/>
<xsd:attribute name="SQLType" fixed="3"/>
<xsd:attribute name="DBTypeName" fixed="number"/>
<xsd:attribute name=IsNullable" fixed="true"/>
<xsd:attribute name="Remarks" fixed=""/>
<xsd:attribute name="NullAllowed"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="CV_Type">
<xsd:attribute name="Direction" fixed="OUT">
<xsd:attribute name="SQLType" fixed="1111"/>
<xsd:attribute name="DBTypeName" fixed="REF CURSOR"/>
<xsd:attribute name="IsNullable" fixed="true"/>
<xsd:attribute name="Remarks" fixed=""/>
<xsd:attribute name="NullAllowed"/>
<xsd:complexType>
<xsd:element name="CV" type="CV_Type"/><xsd:choice>
<xsd:complexType name="ACNO_Type">
<xsd:simpleContent>
<xsd:extension base="xsd:integer">
<xsd:attribute name="Direction" fixed="IN"/>
<xsd:attribute name="SQLType" fixed="3"/>
<xsd:attribute name="DBTypeName" fixed="number"/>
<xsd:attribute name=IsNullable" fixed="true"/>
<xsd:attribute name="Remarks" fixed=""/>
<xsd:attribute name="NullAllowed"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="CV_Type">
<xsd:attribute name="Direction" fixed="OUT">
<xsd:attribute name="SQLType" fixed="1111"/>
<xsd:attribute name="DBTypeName" fixed="REF CURSOR"/>
<xsd:attribute name="IsNullable" fixed="true"/>
<xsd:attribute name="Remarks" fixed=""/>
<xsd:attribute name="NullAllowed"/>
<xsd:complexType>
Generate the request manually as a string in your script or by using the XML connector in the map. If you use a script to generate the XML, remember to escape the double quotes for the attributes when building the string. The following example shows a request XML instance created based on the schema:
<Request>
<Parameter>
<ACNO Direction="IN"
SQLType="3"
DBTypeName="NUMBER"
IsNullable="true">10019</ACNO>
<CV Direction="OUT"
SQLType="1111"
DBTypeName="REF CURSOR"
IsNullable="true"></CV>
</Parameter>
</Request>
<Parameter>
<ACNO Direction="IN"
SQLType="3"
DBTypeName="NUMBER"
IsNullable="true">10019</ACNO>
<CV Direction="OUT"
SQLType="1111"
DBTypeName="REF CURSOR"
IsNullable="true"></CV>
</Parameter>
</Request>
Note: The Request and Parameter elements always start the XML request instance.
The first parameter in this example is defined in the XML instance as ACNO. ACNO becomes the first element in the request. The parameter name also has a corresponding type definition. The values in the type definition become the attributes. ACNO has a type definition named ACNO_Type. In the definition of ACNO_Type, there are attributes with values. The attributes, Direction, SQLType, DBTypeName, and IsNullable are all attributes with the values they contain in the schema. If the parameter is an input or in-out parameter, it is passed in as a data element of the parameter name. In this example, ACNO has 10019 as its value.
The second parameter is called CV and is a REF CURSOR. The attributes for the CV_Type are defined in the schema. They are the same as for ACNO, but the data values are different. The data values are Direction, SQLType, DBTypeName, and IsNullable. No data value is passed, since the parameter is an output parameter. This is captured by the component and put in the WebRowSet XML response.
JDBC Stored Procedure Invoker Properties
Property | Description |
|---|---|
Repository Home | Directory where all schema files are generated and stored. For every stored procedure that you select, the invoker generates a corresponding request and response schema file. These files are stored in the repository home. The value of the User ID property and a hard-coded "SP" directory are used to create a directory under Repository Home. If the User ID is not specified, then SP is created in a directory called No_UserId. Tip... If you do not know the path of your temporary directory, locate it by typing %tmp% at the command prompt. Example #1 Repository Home = %tmp% User Id = tester The request and response schemas are created in %tmp%\tester\sp. Example #2 Repository Home = %tmp% User Id = (blank) The request and response schemas are created in the %tmp%\NO_USERID\sp Note: The Repository Home directory has a generated subdirectory called spInvokerBaseSchemas, which contains the base schemas: invokerBase.xsd, invokerRequest.xsd, and invokerResponse.xsd. |
Recreate Schema | Indicates whether to recreate the request and response schema for every database session. By default, Recreate Schema is set to False. This ensures that the JDBC Stored Procedure Invoker does not recreate the request and response schema for every database session. If the procedure has changes, set the value to true. This indicated that the component must generate a new request and response for the procedure if the schemas already exist. |
Procedure Schema | Optional: If a procedure is contained within a particular schema, specify the schema in which to search for the procedure. If this field is not specified, all schemas in the database are searched. |
Driver | JDBC driver to load and use. For example: oracle.jdbc.driver.OracleDriver |
Host URL | JDBC URL connection to the database. For example: jdbc:oracle:thin:@dbserver1:1521:mydbname |
User ID | User name for the database session. Note: Provide the user ID for the database session only if it is configured for your database. |
Password | Password for the database session. |
Jar Location | Directory that contains the JAR files that are required to load the JDBC driver. Note: You cannot append multiple paths to the value. All driver JAR files must be located in the same folder. Caution! Always use the latest JAR files for a particular database version. |
Global Transaction | Select this option to make it a global. |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the selected stored procedure. Requires two DJMessage objects, one that contains the XML request and one to capture the XML response. The maximum size limit for DJMessage is 512 MB. |
Connect | Opens a persistent connection to the database |
Disconnect | Closes an existing database connection and performs any clean up actions required. |
BeginTransaction | Starts an implicit transaction for the session that can be committed or rolled back. |
CommitTransaction | Commits any insert, update, or delete operations made on the database. |
RollBackTransaction | Rolls back any SQL statements that have been sent to the database using the WebRowSet XML format. |
Tip... Call Connect and Disconnect explicitly in your process flow.
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Request XML message used to execute the procedure. |
TargetMessage | Response XML message returned from executing the procedure. The target message is in WebRowSet XML format. |
Supported Action Properties
Action | Property | Description |
Execute | Stored Procedure | Stored procedure that the JDBC Stored Procedure Invoker should invoke. For example: StoredProcedure=SP_RS. Select a stored procedure from the list. Based on your selection, the JDBC Stored Procedure Invoker automatically creates a request and response schema in the repository home folder. Note: The spInvokerBaseSchemas contains the base schemas invokerBase.xsd, invokerRequest.xsd, and invokerResponse.xsd. The user interface displays a reference to the request and response schemas. |
Execute | Source Schema | Name of the schema created based on metadata from the stored procedure. The source schema is used to define the structure of the request that is passed in at run time. The response schema file is located in the repository home folder. The JDBC Stored Procedure Invoker automatically maps the path to the request schema in the repository home. |
Execute | Target Schema | Name of the response schema file created by the JDBC Stored Procedure Invoker, based on the chosen stored procedure. The response schema file is located in the repository home folder. JDBC Stored Procedure Invoker automatically maps the path to the response schema based on your entry in the Repository Home instance property. |
Errors
Error Code | Error Name | Description | Reason |
19 | ERR_OPENERR | Error while connecting to the database | Returned when an exception occurs while connecting to the specified database |
27 | ERR_CLOSERR | Error while disconnecting from the database | Returned when an exception occurs while disconnecting from the specified database |
98 | ERR_TRANSACT | Error while using transaction method like commit, rollback. | Returned when an exception occurs while using transaction methods like commit and rollback |
89 | ERR_EXECUTE | Error while running the stored procedure | Returned when an exception occurs while running the stored procedure (Execute method) |
WebRowSet Update Invoker
The WebRowSet Update Invoker uses a WebRowSet as input and applies updates (INSERT, DELETE, or MODIFY) to a target database.
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the source message for the invoker. The body of the message must contain the WebRowSet statement as the input for the update. |
TargetMessage | Optional name of the target message for the invoker If specified and the target supports BatchResponse, the BatchResponse is returned in the message body. |
Supported Action Properties
Action | Property | Description |
|---|---|---|
Execute | TargetType | Multimode target type. |
Execute | TargetServer | Target server host name. |
Execute | TargetDatabase | Database updated by the invoker. |
Execute | TargetTable | Name of table where update is applied. |
Execute | Username | User ID to access the target database. The connection is limited to the access rights of the user ID that you enter. |
Execute | Password | Password to access the target database |
Execute | UpdateKeys | Field names in the target table to use as the keys for the update. Required for MODIFY and DELETE. If you specify multiple field names, use commas to separate them. UpdateKeys are also known as ActionKeys. |
Note: Any property value you set in the source message overrides the invoker property value.
XQuery Invoker
XQuery Invoker extracts data from an XML document based on the XQuery expression. You must have working knowledge of XML and XQuery.
DataConnect 11.0 version supports XQuery Invoker 1.1 and 1.2 versions.
The XQuery Invoker does the following:
• Extracts data from complex XML documents
• Accepts dynamic sources, targets, and queries
• Supports a static source document, a dynamic XQuery expression, and vice versa
XQuery Invoker Properties
XQuery Invoker 1.1.0 supports two instance properties.
Property | Description |
|---|---|
Dynamic XQuery or XML Source Document | Location or URL of XQuery or XML source file |
Source XML Document | Location of the source XML document |
Supported Actions
Action | Description |
|---|---|
Execute | Executes the supported parameters and properties. |
Supported Action Parameters
Action | Parameter | Description |
|---|---|---|
Execute | SourceMessage | Name of the source message for the invoker |
TargetMessage | Name of the target message for the invoker |
Supported Action Properties
This section provides the action properties for XQuery Invoker versions 1.1.0 and 1.2.0.
XQuery Invoker 1.1.0 Action Properties
In the step property, you can provide a URL to either a source XML document, or an XQuery file by setting the step property value (design time) or as the source DJMessage (run time).
If the input is a source XML file, then the file content can be passed in the source message.
The tables below outline the various possible step property combinations available in XQuery Invoker 1.1.0.
Note: Source Message is the value supplied within the source DJMessage.
XML Source | XQuery Expression | Description | Example |
|---|---|---|---|
Design Time | |||
URL | URL | Provide URL to the XML source at design time | C:\people.xml |
Provide URL to the XQuery file at design time | C:\people.xq | ||
Combination of Design and Run Time | |||
Source Message (URL) | URL | Provide URL to the XML source at run time | srcMsg.Body = "C:\people.xml" |
Provide URL to the XQuery file at design time | C:\people.xq | ||
Source Message (Content) | URL | Provide soure XML content at run time | msg.Body = fileread("C:\people.xml") |
Provide URL to the XQuery file at design time | C:\people.xq | ||
URL | Source Message (URL) | Provide URL to the XML source at design time | C:\people.xml |
Provide URL to the XQuery file at run time | srcMsg.body="C:\people.xq" | ||
URL | Source Message (Content) | Provide URL to the XML source at design time | C:\people.xml |
Provide XQuery file at run time | srcMsg.body=fileread("C:\people.xq") | ||
XQuery Invoker 1.2.0 Action Properties
XQuery Invoker 1.2.0 supports the following action properties.
Action | Property | Description |
|---|---|---|
Execute | XML Source | The Execute action accepts inputs: • At design time as a URL • At run time as either content or URL through the DJMessage object |
Execute | XQuery Expression | The Execute Action accepts inputs: • At design time as a URL • At run time as either content or URL through the DJMessage object |
Errors
This table lists the error conditions that are specific to XQuery Invoker.
Code | Name | Description | Reason |
|---|---|---|---|
12 | ERR_NOSOURCE | Invalid XML source | XML source file provided is corrupt or invalid. |
34 | ERR_INVALID | Invalid XQuery expression | XQuery expression provided is invalid. |
50 | ERR_UNSPECIFIED | Run time exception | Run time exception encountered. |
Last modified date: 08/02/2023