DocuSign Request node

Use the DocuSign Request node to connect to DocuSign and issue requests to create, retrieve, update, or delete objects such as documents, attachments, envelopes, and recipients.

The DocuSign Request node is available on Windows, AIX®, and Linux® systems.

This topic contains the following sections:

Purpose
Using the DocuSign Request node in a message flow
Terminals and properties

Purpose

You can use the DocuSign Request node in a message flow to connect to DocuSign and perform actions on objects, including the following:

Attachments: Create, retrieve, update, or delete attachments
Documents: Retrieve, delete, bulk create, or update documents
Envelope recipients: Retrieve, delete, bulk create, or update recipients
Envelopes: Create, retrieve, or update envelopes

The DocuSign Request node operations are synchronous and non-transactional, which means that, if a message flow fails and rolls back after the DocuSign Request node, the operation on the data source will still complete.

The DocuSign Request node is contained in the DocuSign drawer of the message flow node palette, and is represented in the IBM® App Connect Enterprise Toolkit by the following icon:

Using the DocuSign Request node in a message flow

For more information about using the DocuSign Request node, see Using DocuSign with IBM App Connect Enterprise. For information about obtaining connection details for DocuSign, see How to use IBM App Connect with DocuSign in the IBM App Connect Enterprise as a Service documentation.

Terminals and properties

When you put an instance of the DocuSign Request node into a message flow, you can configure it. For more information, see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those properties without a default value) are marked with an asterisk.

The DocuSign Request node terminals are described in the following table.

Terminal	Description
In	The input terminal that accepts a message for processing by the node. The DocuSign Request node is driven by a message that arrives on the In terminal.
Out	The output terminal from which the message tree is propagated. The output message tree contains the object that is returned from the DocuSign connector.
No Data	If the DocuSign connector is invoked successfully but the action returns no data (as no records were found), the message is sent to the No Data terminal. If an action returns no data and the No Data terminal is not wired, an exception is thrown.
Failure	If an error occurs in the DocuSign Request node, the message is sent to the Failure terminal.

The following tables describe the node properties. The columns headed M indicate whether the property is mandatory (marked with an asterisk on the panel if you must enter a value when no default is defined). The columns headed C indicate whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The DocuSign Request node Description properties are described in the following table:

Property	M	C	Default	Description
Node name	Yes	No	The node type, DocuSign Request	The name of the node.
Short description	No	No		A brief description of the node.
Long description	No	No		Text that describes the purpose of the node in the message flow.

The DocuSign Request node Basic properties are described in the following table.

Property	M	C	Description
Action	Yes	No	This property shows the action to be performed by the DocuSign Request node. The action is defined through the Connector Discovery wizard, and is then displayed in the Action property in read-only format. Click Launch Connector Discovery to start the Connector Discovery wizard for the DocuSign connector, and define the action that you require.
Object	Yes	No	This property shows the object on which the specified action is to be performed. The object is defined through the Connector Discovery wizard, and is then displayed in the Object property in read-only format.
Schema base name	Yes	No	The name of the schema files that describe the format of the request message and response message that are sent and received from the DocuSign connector. The schema files can be used by a Mapping node to map the data values. You can open the schema by clicking the Open request schema or Open response schema buttons. A request schema is generated only if the selected action and object require a request message. If the action that is selected is of type `RETRIEVE` or `DELETE`, only the response schema is returned by the connector. For more information about the schema files, see Using DocuSign with IBM App Connect Enterprise.
Connector properties	No	No	Depending on the object and action that is specified for the DocuSign connector during discovery, the Connector properties section shows the properties that have been set for the connector through the Connector Discovery wizard. If no connector properties were set during discovery, this section is not displayed in the Basic tab.

The DocuSign Request node Connection properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Policy	Yes	Yes		This property specifies the name of the policy that contains the details of the security identity that is used for the connection. The policy has a type of `DocuSign` and is defined in a policy project.	policyUrl
Timeout (seconds)	No	Yes	60	This property specifies the time (in seconds) that the node waits for DocuSign to process the operation. The default is 60 seconds.	timeout

The DocuSign Request node Filter properties are described in the following table.

Property	M	C	Default	Description
Filter options	No	Yes		The properties in the Filter options section control which objects are to be operated upon when the DocuSign Request node executes. The filter options are defined in the Connector Discovery wizard during discovery, but you can then modify the values by using the Edit button in the Filter tab of the node. If no filter conditions were set during connector discovery, no properties are shown in the Filter options section of the tab. The property value can be either a text value or an ESQL or XPATH expression that is resolved from the contents of the message that is passed to the DocuSign Request node as it executes.
Maximum number of items to retrieve	No	Yes	15	The Maximum number of items to retrieve property specifies the maximum number of items that can be retrieved from the DocuSign connector. This property applies only to the `Retrieve` action. This property is defined in the Connector Discovery wizard during discovery, but you can then modify the values in the Filter limit section of the DocuSign Request node. If no filter conditions were set in the Connector Discovery wizard during connector discovery, this property is not shown in the Filter tab of the node.
If the limit is exceeded	No			The If the limit is exceeded property specifies the action to be taken if the number of items that are retrieved from the connector exceeds the specified maximum. This property applies only to the `Retrieve` action. You can choose one of the following actions: Report an error. Process the maximum number of items from the collection, as set by the Maximum number of items to retrieve property. This property is defined in the Connector Discovery wizard during discovery, but you can then modify the values in the Filter limit section of the DocuSign Request node. If no filter conditions were set in the Connector Discovery wizard during connector discovery, this property is not shown in the Filter tab of the node.

The DocuSign Request node Request properties are described in the following table.

Property	M	C	Default	Description
Request mode	No	No	None	This property determines the message that is sent to the connector when the selected action (specified during connector discovery) is performed. The Request mode is set during connector discovery, by using the Connector Discovery wizard. If you want to edit this property, start the Connector Discovery wizard by clicking Launch Connector Discovery in the node property editor. This property can be set to either of the following values: Using Map inputs When this value is selected, the connector takes its input data from the locations described in the Map inputs table, and applies the mapping logic that was defined during connector discovery. Using Data location When this value is selected, the connector takes its input data from the single location that is defined in the Data location field, without applying any mapping logic. As no mapping logic is applied to this input data, it must match the request schema of the connector.
Map inputs	No	No		The Map inputs table is used to define the input that is available for use when building the message to be sent to the connector, and for defining the filter values for operations that require a filter. The entries in the Map inputs table describe specific parts of the message assembly and the schemas that define them: Input name is the unique name for the row in the map inputs table. Input location specifies the location in the message assembly. Message domain specifies the parser for the input location. Schema location specifies the JSON schema that describes the message at the input location. Schema root specifies the location in the schema file that describes the message structure. This is required only if the JSON schema is not at the root of the schema document. By default, the table contains data that describes a generic input message and the structured parts of the local environment tree. You can add an entry to the Map inputs table to specify the location of a message in the message assembly that is described by an associated JSON schema. If there is a preceding message flow node that defines the structure of a JSON message arriving on this node's input terminal, the schema is located and suggested as an option that you can use. For more information about using JSONata mapping, see Configuring mapping for discovery connector request nodes and JSONata mapping example.
Data location	Yes	No	$Body	This property specifies the location in the incoming message tree from which data is retrieved to form the request that is sent from the request node. The default value, `$Body`, represents the incoming message body. You can enter any XPath or ESQL expression that defines the location of the message tree to serialize and send. This property applies only when the Request mode property is set to Using Data location.

Property

Default

Description

Request mode

None

This property determines the message that is sent to the connector when the selected action (specified during connector discovery) is performed. The Request mode is set during connector discovery, by using the Connector Discovery wizard. If you want to edit this property, start the Connector Discovery wizard by clicking Launch Connector Discovery in the node property editor.

This property can be set to either of the following values:

Using Map inputs: When this value is selected, the connector takes its input data from the locations described in the Map inputs table, and applies the mapping logic that was defined during connector discovery.
Using Data location: When this value is selected, the connector takes its input data from the single location that is defined in the Data location field, without applying any mapping logic. As no mapping logic is applied to this input data, it must match the request schema of the connector.

Map inputs

The Map inputs table is used to define the input that is available for use when building the message to be sent to the connector, and for defining the filter values for operations that require a filter.

The entries in the Map inputs table describe specific parts of the message assembly and the schemas that define them:

Input name is the unique name for the row in the map inputs table.
Input location specifies the location in the message assembly.
Message domain specifies the parser for the input location.
Schema location specifies the JSON schema that describes the message at the input location.
Schema root specifies the location in the schema file that describes the message structure. This is required only if the JSON schema is not at the root of the schema document.

By default, the table contains data that describes a generic input message and the structured parts of the local environment tree.

You can add an entry to the Map inputs table to specify the location of a message in the message assembly that is described by an associated JSON schema. If there is a preceding message flow node that defines the structure of a JSON message arriving on this node's input terminal, the schema is located and suggested as an option that you can use.

For more information about using JSONata mapping, see Configuring mapping for discovery connector request nodes and JSONata mapping example.

Data location

Yes

$Body

This property specifies the location in the incoming message tree from which data is retrieved to form the request that is sent from the request node. The default value, $Body, represents the incoming message body. You can enter any XPath or ESQL expression that defines the location of the message tree to serialize and send.

This property applies only when the Request mode property is set to Using Data location.

The DocuSign Request node Result properties are described in the following table.

Property M C Default Description

Result data location

Yes

Property	M	C	Default	Description
Result data location	Yes	No	$ResultRoot	This property specifies the location in the message that is copied to the Output data location field in the output message. For example, `$ResultRoot` (the default) inserts the result message into the output tree at the location that is specified by the Output data location property. For more information, see Combining a result message with an input message when fetching data from external systems.
Output data location	Yes	No	$OutputRoot	This property specifies the message tree location to which the DocuSign Request node sends output. The part of the message that is copied is specified by the Result data location property. The default value specifies that the retrieved message is copied to the root of the outgoing message. See Combining a result message with an input message when fetching data from external systems.
Copy local environment	No	No	Selected	This property controls whether to copy the incoming local environment or propagate the incoming local environment. By default, this check box is selected, which specifies that the local environment is copied so that the incoming local environment is preserved. The additions to the local environment are visible only to nodes downstream of this node. If this check box is cleared, the incoming local environment is used for the outgoing message. Any modifications that are made to the local environment by this node are visible to both downstream and upstream nodes after this node has completed.

$ResultRoot

This property specifies the location in the message that is copied to the Output data location field in the output message.

For example, $ResultRoot (the default) inserts the result message into the output tree at the location that is specified by the Output data location property.

For more information, see Combining a result message with an input message when fetching data from external systems.

Output data location

Yes

$OutputRoot

This property specifies the message tree location to which the DocuSign Request node sends output. The part of the message that is copied is specified by the Result data location property. The default value specifies that the retrieved message is copied to the root of the outgoing message.

See Combining a result message with an input message when fetching data from external systems.

Copy local environment No No Selected This property controls whether to copy the incoming local environment or propagate the incoming local environment. By default, this check box is selected, which specifies that the local environment is copied so that the incoming local environment is preserved. The additions to the local environment are visible only to nodes downstream of this node. If this check box is cleared, the incoming local environment is used for the outgoing message. Any modifications that are made to the local environment by this node are visible to both downstream and upstream nodes after this node has completed.

The DocuSign Request node Response Message Parsing properties are described in the following table.

Property	M	C	Default	Description
Message domain	Yes	No	JSON	The domain that is used to parse the response message. By default, the message that is propagated is in the JSON domain. You cannot specify a different domain.
Message model	No	No		The name or location of the message model schema file in which the incoming message is defined. You cannot set this property.
Message	No	No		The name of the response message. The node detects the message type automatically; you cannot set this property.
Physical format	No	No		The name of the physical format of the response message. You cannot set this property.

The DocuSign Request node Validation properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	No	Yes	Content and value	This property controls whether request messages are validated against the request schema that is discovered during connector discovery, and is enabled by default. You can set this property to one of the following values: None Turn off validation of request messages. Content and value Validate request messages against the discovered request schema. Content checks include content validation and composition, and value checks include checks for whether the value conforms to data type, length, range, and enumeration. This option is set by default. Inherit Use the validation settings that are provided with the input message tree in preference to any supplied on the node. Inherit therefore resolves to None or Content and value. If Inherit is selected, the other validation properties on the tab are not available.	validateRequestMaster
Failure action	No	No	Exception list	This property controls the action that is taken when a validation failure occurs. You can set it to one of the following values: Exception An exception is thrown on the first validation failure encountered. The failure is also logged in the user trace if you have asked for user tracing of the message flow, and validation stops. Use this setting if you want processing of the message to halt as soon as a failure is encountered. Exception list An exception is thrown if validation failures are encountered, but only when the current parsing or writing operation has completed. Each failure is also logged in the user trace if you have asked for user tracing of the message flow, and validation stops. Use this setting if you want processing of the message to halt if a validation failure occurs, but you want to see the full list of failures encountered. This option is set by default. User trace All validation failures are logged to the user trace, even if you have not asked for user tracing of the message flow. Use this setting if you want processing of the message to continue regardless of validation failures (where it is possible to do so). Local error log All validation failures are logged to the error log (for example, the Event Log on Windows). Use this setting if you want processing of the message to continue regardless of validation failures (where it is possible to do so).
Response validation options	No	No		Validation of the response message is not controlled by this node. The discovery connector builds the response message and produces a valid message that matches the schema.

The DocuSign Request node Monitoring properties are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.