Design

Back Next

Service Connector Bindings

For each action in a service connector, the Binding options enable you to specify the interface and parameters required to communicate with a service.

Binding Properties

Specify values for these options:

URL

: Enter the URL of the REST Service.

Verb

: Choose how to send data to the service:

GET

HEAD

OPTIONS

, and

TRACE

: Process Designer automatically generates the query parameters.

POST

PUT

PATCH

, and

DELETE

: Process Designer adds a

Binding Type

field from which you can then select the value as

JSON

JSON Unwrapped

Form

URL

, or

Custom

. If you select

Custom

, a

Body

field appears where you can type the request that is sent to the service. By default,

JSON

is selected for the

POST

PUT

, and

PATCH

verbs, and

None

is selected for the

DELETE

verb. Consult the API documentation to determine what you should enter.

Multi Using

: This option determines how query string parameters are generated when you need to specify multiple values for a parameter. Choose one of the following:

Semicolon separated

: for a semicolon-separated multi-select list, Process Designer adds input parameter values as a single string. (For example, ?param=a;b;c
). This is the default.

Comma separated

: for a comma-separated multi-select list, Process Designer adds input parameter values as a single string. For example, ?param=a,b,c
.

Append brackets

: for a semicolon-separated multi-select list, Process Designer maps semicolon-separated values to multiple query parameters of the same name, and appends [] to the parameter name. For example, colors[]=red&colors[]=blue&name=JW
.

Append numbers

: for a semi-colon separated multi-select list, Process Designer maps semicolon-separated values to multiple query parameters of the same name and adds a number to the end of the field name, that is, 1..N. For example, colors1=red&colors2=blue&name=JW
.

Authentication Type

: You have two options to define the authentication information that the service requires: Basic or Custom. If you choose:

Basic

, enter the user name and password, if required.

Enter text or an XQuery expression in the user name and password fields. If you enter an XQuery expression, you can pass the password value through a connection instead of hard coding it in the service connector. Click the glass icon to view the password.

Select the

Expression in Password

check box to retain the password that you enter and also export the password when you export the service connector.

If the password contains an ampersand (&) character, when you test the service connector, the action fails. Additionally, if you use the same service connector in an app connection and process, the process invocation also fails.

Custom

, add the security parameters based on the service requirements. For example, you might need to send signed data using an HTTP header.

Enforce Multipart Request

: Select this check box to enforce a multipart request in a service connector binding for combining one or more sets of data into a single body, separated by delimiters. The check box is cleared by default. After you select this option, you can upload attachments and transfer data of several types in a single request payload. For example, you can transfer a file along with a JSON object using a multipart request. The

Enforce Multipart Request

check box is available only for the POST, PUT, PATCH, and DELETE verbs.

HTTPS/Mutual Authentication

: Select this check box if the action must use a custom client certificate for mutual authentication. You can configure one custom client certificate for each action. If selected, the

Keystore File Path

and

Keystore Password

fields appear. You must place the keystore file on the Secure Agent machine.

You can configure custom client certificates for service connectors that run on Secure Agents. When you configure a custom keystore file for a service connector and also specify a client certificate using the

javax.net.ssl.keyStore

property in the Process Server properties, the custom keystore file configured in the service connector takes precedence. If the service connector authentication fails, the client certificate configured in the

javax.net.ssl.keyStore

property is ignored and the request fails.

Keystore File Path

: Enter the path and file name of the Java KeyStore (JKS) file on the Secure Agent machine.

Keystore Password

: Enter the password to open the keystore file.

Other Parameters

Use this section to add input parameters required by the service. The value may be specified as a literal or expression. Refer to documentation from the service you are using.

To add a row and enter multiple parameters, click the +
sign. To remove a row, click the X
.

For each row, enter:

Name
: the name of the parameter as specified within the service being called.

Content
: the value to specify for the parameter, if any.

Click Show Advanced
to select these optional parameters for the Binding:

Sign With
: The value that is computed will first be signed using SHA1, and the result of the signature will be this value.

Sign Using
: Choose to sign the field using SHA1 or SHA256.

Encode Using
: Choose to encode the field as Base64 and Hex64Upper.

Temp
: If checked, Process Designer will not generate a parameter when using GET or POST. For more information, see the Parameters described here: Input Tab.

Attachment Base64
: The base64 encoding of the attachment associated with the <inputName>.

Attachment Name From
: The file name of the attachment associated with the <inputName>.

Click Hide Advanced
to hide the fields.

HTTP Headers

If the service requires one or more HTTP headers, enter the Name and Content (value of the parameter) for each header in this section.

To define a SOAP-based service connection, you must add both the "SOAPAction" and "Content-Type" headers. The value of SOAPAction can be empty, dynamically set using GET, or defined in the WSDL.

If the service does not set the content-type in the response header, the service connector attempts to infer the content type from the payload. For example, if the response starts and ends with either "{...}" or "[...]", the response is parsed as JSON. If the response payload starts with an angle bracket ("<"), it is treated as XML. If the response payload cannot be parsed due to malformed JSON or XML, it is processed as a regular string.

If the response Content-Type header contains the term

application

in the first part and the term

json

in a subsequent part, Application Integration infers the response payload type as JSON. Similarly, if the response Content-Type header has the term

text

in the first part and the term

xml

in a subsequent part, Application Integration infers the payload type as XML.

As you type in the Name field, Process Designer displays commonly used values, including:

Accept-Charset

Accept-Encoding

Accept-Language

Content-Type

SOAPAction

Some services request an MD5 signature. You can generate an MD5 signature in the

HTTP Headers

section of service connector actions.

To generate an MD5 signature, perform the following steps:

Enter a name for the HTTP header. For example, enter

Signature

Go to

source

Expression Editor

Under

type

, select

XQuery

Under

Insert Field

, select

PAYLOAD_DIGEST_MD5

When you test or run the service connector, the used variable contains an MD5 checksum for the generated request payload.

Content Type and Character Sets

You can determine the charset used for a request payload as noted here:

Specify a charset value in the Content-Type header. In this case, the header determines the charset of the request payload. In this case, the charset is based on the value specified in the header unless the request format is an attachment type, in which case each part of a multipart/form-data request will be treated separately. If you set the Content-Type and want the service connector to append the default charset automatically, add a semi-colon after the specified Content-Type, as shown here:

Content-Type=application/json;

Do not specify a charset value in the Content-Type header so this value can be set automatically based on the request format. To ensure that the content can be decoded correctly, the service connector appends the default charset (UTF-8) to the Content-Type. For example, the value might be set as follows:

Content-Type=application/json;charset=UTF-8