The IBM® Cast Iron Connector Development Kit (CDK) wizard is for developers who want to use the Cast Iron Studio (hereafter called Studio) development platform to develop and deploy plug-in connectors that extract data from application systems or other data sources. The wizard provides a method to build connectors for endpoints that are not a part of the Cast Iron product. You can use the wizard to build connectors to entities that expose either a web service or REST API. The connectors developed using the wizard do not require coding.
The wizard guides you through three windows, where you specify the basic connector information, the various activities, and their input and output types. The wizard then generates the basic skeleton of the orchestrations.
This article will explain password handling, configuration of ListObjects and DescribeObject orchestrations, and fault handling.
When creating a custom connector, the first step is to define the endpoint connection field information. If the endpoint requires a password, then there are two formats to specify it (see Figure 1):
- If the format is set as
STRING, then it is used to display plain text.
- If the format type is
PASSWORD, it is used to display a special character to hide the text value that is entered in the field. When the request is sent by default, it is base64 encoded. Therefore, when you develop orchestrations in a connector project, you must decode the password and later start the HTTP or Web Service method to connect to the endpoint.
Figure 1. Add Connection Fields window
Figure 2 displays a TestConnection orchestration that has "Provide Service" as the starter activity. This activity provides the connection information in the header.
Figure 2. Test Connection Orchestration
The Decode Password Configuration Property function must be applied to "Password" (see Figure 3). The result of this function is copied to a string variable, for example "Password". If "Password" is not encoded, then the string variable Password will be empty. In that case, the password from the header must be mapped to the string variable (Password). This string variable (Password) will be used to start the endpoint in the login method.
Figure 3. Map variables activity
Password handling is applicable to all orchestrations that are needed for the custom connector.
Configuring the ListObjects orchestration
The ListObjects orchestration returns the list of objects that are applicable for each connector activity.
The response of the ListObjects activity must have the namespace set as
For example, if the list of objects to be returned are Product, Invoice, and Usage, then ListObjectsResponse must be of the following form:
<ListObjectsResponse xmlns="http://www.approuter.com/schemas/cdk/api/"> <objectType label="Product">Product</objectType> <objectType label="Invoice">Invoice</objectType> <objectType label="Usage">Usage</objectType> </ListObjectsResponse>
If the namespace is not set, then no objects are returned as part of this activity.
Configuring the DescribeObject orchestration
The DescribeObject orchestration provides input and output that enables you to successfully work with an object being exposed through an activity. The endpoint may or may not expose operations to discover its objects and properties
- If the endpoint provides the operation to discover the object
properties, then DescribeObjectResponse should be set to the following
typeNS: Object namespace baseTypeNS: Object namespace baseType: to the base object type as mentioned in the wsdl
- If the endpoint does not expose any operation, but are defined in
wsdl, then set the following:
typeNS: Object namespace baseTypeNS:http://www.approuter.com/schemas/cdk/api/ baseType: cObject
Complete the following steps if an activity requires a fault to be thrown while running an orchestration:
- In the Configure panel of the Provide Service activity, you can add a
new fault in the "May throw the following Faults" section, as shown in
Figure 4. Creating the required faults
- Specify a name for the fault in the Fault Name field.
- Browse and choose the fault element either from the wsdl or the user
defined schema, as shown in Figure 5.
Figure 5. Adding a fault
- To send a reply with fault, choose Send Reply With Fault from the Web Service endpoint.
- In the Configure panel, choose the right type of fault that needs to
be thrown, as shown in Figure 6.
Figure 6. Send Reply With Fault activity
- In the Map Inputs panel, map the required information to the fault
schema as shown in Figure 7.
Figure 7. Map Inputs of Send Reply With Fault activity
In this article, your learned to easily configure the base orchestrations that are needed for all connectors developed using the CDK wizard. You also learned some tips about password handling and fault handling.
The authors would like to thank Rajath Ramesh and Roshini Sunil for reviewing and providing valuable suggestions for this article.
- WebSphere Cast Iron 6.3 Information Center
- WebSphere Cast Iron Cloud Integration product page
- IBM Redbook: Getting Started with IBM WebSphere Cast Iron Cloud Integration
- WebSphere Cast Iron Cloud Integration Support page