Design > Designing Service Connectors > Option 1: Creating a New Service Connector
  

Option 1: Creating a New Service Connector

You can create a service connector by defining properties and specifying functions and variables. You can also define the actions associated with a service connector.
To create a service connector, perform the following steps:
  1. 1In Application Integration, click New > Service Connectors.
  2. 2In the New Asset dialog box, click Service Connector using Form, and then click Create.
  3. The image shows the New Asset dialog box.

Defining Properties

To create a service connector and define the properties, perform the following steps:
  1. 1In Application Integration, click New > Service Connectors.
  2. 2In the New Asset dialog box, click Service Connector using Form, and then click Create.
  3. 3Define the following basic properties for the service connector on the Definition tab:
  4. 4Click + to add the connection properties to connect to this service. Specify the following details for each connection property in the Connection Properties section:
  5. The following image shows a sample service connector:
    The image shows a sample service connector.
  6. 5To edit the connection properties, click anywhere on the row that contains the connection property.
  7. All the properties in the row become editable.
  8. 6Click Save.
For more information about the actions and process objects that define service connectors, see Defining Actions and Creating Service Connector Process Objects.

Specifying Functions and Variables

To configure service connectors, you may need to specify variables and functions to define bindings, output fields, and other properties.

Built-in Variables

You can reference these variables in a service connector using an XQuery expression:
Variable
Variable Type
Description
$VariableName
All connection properties
Properties, input and Other Parameters can be specified using this format.
$ResponseStatusCode
Output field mapping
HTTP response code.
$ResponseHeaders
Output field mapping
Contains the HTTP response header in an element list where each item is:
<header name="Content-Type">text/plain</header>
For example:
$ResponseHeaders[@name = "Content-Type"]/text()
$RESTResponse
Output field mapping
Contains the RESTResponse XML data, including the headers and code. Visible in the Test Results for the Service Connector.

Output Field Mapping Functions

When you define bindings in the service connector, you can use many functions in the Expression Editor.
For information on all the available functions, see Using Functions and Using the Expression Editor.
The following table describes functions available for service connector output field mappings:
Function
Syntax
Description
responseHeaderExists
svc:responseHeaderExists($ResponseHeaders, headerName ) : boolean
Returns a Boolean value that indicates if a header parameter exists within the response.
getResponseHeader
svc:getResponseHeader( $ResponseHeaders, headerName, defaultValue ) : string
svc:getResponseHeader( $ResponseHeaders, headerName ): string
Returns a response header value. If the header parameter is not defined, this function returns the optional default value.
getResponseHeaderNames
svc:getResponseHeaderNames( $ResponseHeaders ) : list of strings
Returns a list that contains the names of all the parameters within a response header.

Defining Actions

On the Actions tab, you can create and describe one or more actions associated with a service connector.
The following image shows the Actions tab:
Choose the row you want to edit and then enter the following information in the Action details tab:
Click + to add a new row.
For each action, specify additional details on the Input, Binding, Output, and Test Results tabs.

Shared Service Actions

Using shared service actions, you can define common inputs, bindings, and outputs, then reuse these definitions in other actions that "inherit" from the parent "abstract" action.
For example, you might have multiple actions which all share the same:
In that case, you can:
  1. 1Define an Abstract type action that contains all of the common definitions:
  2. 2Create multiple Inherit type actions that use those common definitions and extend or add to certain parameters.
  3. 3For example, an Inherit action can:
For example:
Notes on Usage
Shared service actions:
After you specify the Inherit Action Type, many fields are disabled.
However, for specific Binding and other options, you can choose to:

Input Tab

Use the Input tab to define input data items that are unique to the service to which you are sending data.
For example:
Depending on the service, you might have no data items or many.
For each item, enter the following properties:
After you enter a value in the input field, you must click anywhere outside the row to save the value.
Use the + icon to add a new item. Click X to delete the current row.

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:

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:
Click Show Advanced to select these optional parameters for the Binding:
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.
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:
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:

Expression Editor for Service Connector Properties

To define the binding parameters, you can use the Expression Editor accessible for the URL, Other Parameters, and HTTP Headers fields.
To open the Expression Editor, click f(x) next to the field you want to edit. When it opens, the Expression Editor gives you access to a list of available functions and the fields defined for the service connector, as shown in this image:
Based on the type selected for the expression, the Expression Editor applies syntax validation. In this case, the post_url field is validated as an XQuery variable.
For more information, see Using the Expression Editor.

Output Tab

Use the Output tab to define how the service connector must parse data returned from a service and place it in variables. Typically, a service returns data in the XML format. If the service returns data in the JSON format, the service connector converts it to the XML format. You can map the XML to output fields in two ways:
  1. 1Directly map the data to a property based on XML tag names or JSON properties.
  2. 2Use Expression to extract elements.
  3. Note: Informatica recommends parsing the XML response by using XML parsing tools such as JDOM and Woodstox, and then extracting values rather than performing a plain string search to match namespaces and tags. If you match plain strings, you might encounter an error because the namespace prefixes are not constant.
The following image shows the Output tab:
The image shows the Output tab.
For each output data item, specify:
After you enter a value in the output field, you must click anywhere outside the row to save the value.
For details on handling HTTP errors, see Checking for HTTP Errors.

Rules and guidelines for using list of simple types

Consider the following rules and guidelines when you use a list of simple types in a service connector:

Simplified XML

Much of the complexity in standard XML, with a mixture of namespace, attributes, siblings, and children, is not needed within Process Designer in order to present data to people designing processes. While you sometimes need to use the XQuery option for Get From, this is not necessary for many applications.
Simplified XML rearranges data within XML so that it can be used by process objects. This rearrangement treats attributes as children, removes namespaces, makes siblings with the same name consecutive, and places text into CDATA sections.
If you select Simplified XML for the Get From option, Process Designer displays a text field. If you do not enter anything in the field, Process Designer processes all of the received XML. If you enter the name of an element, Process Designer begins simplifying at this element, only processing this element and elements nested within it.
If you type a period ("."), this is treated as an empty field. (This is the default.)

Checking for HTTP Errors

When you send a request to a server and it cannot complete the request, it returns an error status code. There are two ways in which a service connector can handle HTTP errors (4xx and 5xx status code in the HTTP response).
  1. 1For each Action defined on the Actions tab, you can select Fail on HTTP error, as shown in the illustration below. By default, this option is enabled. If the HTTP request returns an HTTP error, the service connector fails.
  2. 2Specify how to handle the HTTP errors for each Action on the Output tab. To implement this option, disable Fail on HTTP error.

Fail on HTTP Error

If you enable Fail on HTTP error and an HTTP error is returned:
HTTP error codes follow the format HTTP_NNN, for example, HTTP_404. The reason string contains the HTTP status message.
Note: Any internal or system errors return SERVICE_CONNECTOR_ERROR and one of the following reason strings:
If you disable Fail on HTTP Error and an HTTP error is returned:
If the target service uses error codes that users might encounter as a matter of course, enable this option to provide process users with meaningful information.
The following image shows the Fail on HTTP error option enabled:

Handle HTTP Errors

To handle HTTP errors for a process, first be sure that you have disabled Fail on HTTP error.
You then need to check the HTTP response status code within the process.
To do this, define an "HTTP Response Status Code" as a variable in the Output tab. You can also specify a variable using $ResponseStatusCode in Expression fields (see the available functions below). In this way, you can pass the status code as part of the service connector's output and handle the response in the process.
These variables, like all variables you create in the Output tab, display when you click Test.
If you check Fail on HTTP error and an HTTP error status code is returned, the output contains a message.

HTTP Response Header Information Using Expression

You can use one of the following to get details from the response headers:
$ResponseHeaders[@name = "Content-Type"]/text();
This constant contains the HTTP response header.
fn:getResponseHeader( $ResponseHeaders, header_name[, default_value] );
Returns a response header value. If the header parameter is not defined, this function returns the optional default value.
fn:responseHeaderExists( $ResponseHeaders, header_name );
Returns a Boolean value that indicates if a header parameter exists within the response.
fn:getResponseHeaderNames( $ResponseHeaders );
Returns a list that contains the names of all the parameters within a response header.

Creating Service Connector Process Objects

On the Process Objects tab, you can define one or more process objects for a service connector to group data and create a structured object. When defined in the service connector, the process objects are available to processes that use the service connector. If, for example, a service returns demographic information such as name, address, and phone number, you might create a single Demographic process object that contains this information.
You can associate each process object with one or more of the data elements returned by the service using the Actions/Output tab.
To create service connector process objects:
  1. 1Create or open an existing service connector.
  2. 2Click the Process Objects tab.
  3. 3Click the + sign to add a new process object or select an existing process object from the list. Each process object appears as a line item on the tab.
  4. 4On the Properties tab, specify the following details for each process object:
  5. 5On the Fields tab, specify the following details for each process object:
For more information about using process objects in a process, see Rules and Guidelines for using Process Objects in a Process.

Testing the Service Connector

When you use the service connector editor, click Test to send a request to the service and display the response data on the Test tab:
Here, you can see the differences between the payload, request, and response data (for illustration purposes only; the actual test results display only request or response data):
If the response includes one or more attachments, you can also download the attachments. The following image shows a multipart response with options to download all the attachments:
The image shows a multipart response with options to download all the attachments.
Generate Process Objects
A process object is usually tied to a specific set of elements. You may sometimes have a large number of identical objects, each of which applies to one set of elements. For example, when you define the data being returned, you create a process object whose sole purpose is to define a subset of returned data. These objects are non-reusable and can only be used by a single process object field. The object names are also the name of a field.
You can also create objects that are reusable. For example, the refType element in NetSuite has two fields: a name and an internalID. Instead of creating many objects, each of which contains these two fields, you can create a single, reusable process object.
  1. 1Click Generate Process Objects to show the process objects that you have defined for the service connector.
  2. 2Select the process objects that you want to make reusable and then click Next.
  3. Process Designer displays a list of generated process objects.
  4. 3Click Finish.

Service Connector Timings

You can see the HTTP Response Parsing time, the HTTP Execution Time, and the Redirection Count in the tab of a service connector.
You can see the following HTTP headers in the Rest Response section of the tab:
HTTP Response Parsing Time
The time that a service connector takes, in milliseconds, to parse a response from the URL you entered in the Binding tab. The HTTP Response Parsing time is usually zero for small requests. For large requests, especially with requests with attachments, the HTTP Response Parsing time increases.
See the HTTP header X-AE-HTTP-RESPONSE-PARSING-TIME-IN-MILLIS for the HTTP Response Parsing Time.
Redirection Count
The number of redirects, if any, made by the URL that you entered in the Binding tab.
For example, if a service request redirects to a service that in turn redirects to another service, the Redirection Count is two. If a service request goes through with no redirects, the Redirection Count is zero.
See the HTTP header X-AE-REDIRECTION-COUNT for the Redirection Count.
Note: If a GET HTTP request redirects to another GET HTTP request, the Redirection Count remains zero. This is a limitation.
HTTP Execution Time
The response time, in milliseconds, of the URL that you entered in the Binding tab. The HTTP Execution Time does not include the response parsing time, or the time taken to by the service connector to perform other tasks.
See the HTTP header X-AE-HTTP-EXECUTION-TIME-IN-MILLIS for the HTTP Execution Time.
The following image shows the X-AE-HTTP-RESPONSE-PARSING-TIME-IN-MILLIS, X-AE-REDIRECTION-COUNT, and X-AE-HTTP-EXECUTION-TIME-IN-MILLIS HTTP headers: