Developing a starter activity for plug-in connectors using the WebSphere Cast Iron Studio Connector Development Kit

Learn how to use the Connector Development Kit (CDK) to develop a plug-in connector that has a starter activity. The article shows you how to deploy the plug-in connector and test it locally on WebSphere® Cast Iron Studio.

Rajath Ramesh (rajathr1@in.ibm.com), Software Engineer, IBM

Photo of Rajath RameshRajath Ramesh is a Software Engineer at the IBM India Software Labs. He started his career with IBM in 2010 as a developer in WebSphere Adapters and incubation projects. He is currently part of the WebSphere Cast Iron development team, specializing in Cast Iron Connectors, Cast Iron Studio, and the Connector Development Kit. He is a co-author of IBM Redbook: Getting Started with IBM WebSphere Cast Iron Cloud Integration.



Roshini Sunil (rosunil1@in.ibm.com), Information Developer, IBM

Photo of Roshini SunilRoshini Sunil is an Information Developer with India Software Labs. She is currently working on information development for Cast Iron Connectors and the Connector Development Kit.



19 June 2013

Also available in Chinese

Introduction

The WebSphere Cast Iron Connector Development Kit (CDK) is a framework or tool that allows you to develop and deploy plug-in connectors. The CDK uses existing capabilities of Cast Iron Studio to develop plug-in connectors. You can develop a plug-in connector easily within a few weeks, as each activity implementation is orchestration-based and requires no coding.

Basically, there are two types of activities: Outbound and Starter. An Outbound activity accepts input, processes it, and provides an output. On the other hand, a Starter activity either listens to an external event or polls an external source periodically, and eventually provides an output. The CDK supported the development of only outbound activities. In Cast Iron V6.3, support of starter activity development was introduced, which is based on polling an external source. This enables plug-in connector developers to seamlessly build Starter activities for their plug-in connectors using the CDK.

Development is completely wizard-based and involves building of orchestrations, which are exposed as activities by the CDK. This article mainly covers how to use the CDK to develop a plug-in connector having a Starter activity. It also covers the steps to deploy the plug-in connector and to test it locally in Cast Iron Studio.

Objectives

You will learn:

  • Design considerations before developing a plug-in connector.
  • How to implement the plug-in connector.
  • How to deploy and test the plug-in connector.

Prerequisites

You should be familiar with IBM® WebSphere Cast Iron Studio, the Cast Iron CDK toolkit, and concepts such as Starter and Outbound activities. You also need to be familiar with using web services and REST APIs provided by SaaS-based applications, such as Salesforce.com®.

System requirements

The following products and assets are required for you to configure and deploy the module:

  • IBM WebSphere Cast Iron Studio V6.3.0.1 or later
  • Required WSDLs and REST URLs to interact with the SaaS application

Designing your plug-in connector

The CDK is best suited to develop plug-in connectors for SaaS applications, which expose web services and REST APIs. As each activity implementation corresponds to an orchestration, you can design your custom implementation using the existing Web Service and HTTP connectors to invoke web service and REST APIs, respectively. Before starting the development of the plug-in connector, you must explore the following:

  • Understand the functionalities and usage of the SaaS application.
  • Methods to communicate to a SaaS application, namely web services or REST APIs. Explore the same using external tools such as SoapUI and Poster, respectively.
  • List of activities that need to be developed as part of your plug-in connector based on business needs.

This article illustrates the steps to develop a plug-in connector to Salesforce.com having a Starter activity. Before starting the development of the SFDCPoller plug-in connector, do the following:

  • Explore Salesforce.com and the use of it in the current market. You can access Salesforce.com using web services and REST APIs.
  • This article uses the web services exposed for performing business activities. Salesforce.com provides multiple WSDLs, each for a different use. In this article, partner.wsdl is used for connector development.
  • Based on the analysis of the operation supported in partner.wsdl and the integration requirements, activities can be designed. This article illustrates the steps to develop a connector with the PollCreatedAccounts activity using query and update operations available in partner.wsdl.

Implementing the PollCreatedAccounts starter activity

The PollCreatedAccounts activity periodically polls Salesforce.com for Account objects that were generated since the previous poll cycle. In this article, the PollCreatedAccounts activity is designed to display AccountID, AccountName, BillingAddress, and Phone fields of the Account object as the output in every poll cycle. After the exploration of partner.wsdl, it is understood that there is no direct operation to poll created accounts from Salesforce.com. However, you have the flexibility to use various operations and develop custom implementation to accomplish the same.

As part of custom implementation of the activity, a new custom field, Pollable, is added to the Account object in Salesforce.com. This field indicates if the Account has already been polled or not. When an account is created in Salesforce.com, the value of the Pollable field is set to True by default. In this scenario, you are going to develop a Starter activity to poll the created Accounts, whose Pollable field value is True. When the Account is polled and processed, the field value is set to False as part of the activity implementation. Therefore, in every poll cycle, you will poll for unprocessed new Account objects from Salesforce.com.

Note: The design and implementation are just an example to demonstrate the flexibility of the CDK, which facilitates custom implementation of the plug-in connector activities.


Developing SFDCPoller with the Starter activity using the CDK Wizard

  1. Open Cast Iron Studio v6.3 and close open projects, if any.
  2. Go to File > New > Create New Connector Project, as displayed in Figure 1.
    Figure 1. Opening the New Connector Project Wizard
    Opening the New Connector Project Wizard
  3. Specify the location to save the connector project by clicking Browse. Type SFDCPoller as the name of the connector project and click OK to launch the CDK Wizard.

    The Connector Wizard tab opens, as displayed in Figure 2.

    Figure 2. The Connector Wizard – connector information
    Connector Wizard – connector information
  4. Specify the following connector details:
    1. In the Name field, specify SFDCPoller as the name of the connector.
    2. In the Description field, type a brief description.
    3. In the Version field, leave the version number as 1.0.0, as it is the first version of the connector.
    4. Add partner.wsdl, which you had downloaded from Salesforce.com (Steps to download partner.wsdl) during the exploration phase. To add the WSDL file, click Browse and select the partner.wsdl file provided by Salesforce.com. Then, click OK.
    5. Click Next. The Add Connection Fields page is displayed.

Adding the connection fields

In this section, you can add fields that are to be displayed in the Endpoint panel of the connector. The order of the fields in this section is maintained in the Endpoint panel. By default, the user name and password fields are pre-configured. The data in the remaining sections corresponds to the selected connection field in this section.

  1. The Salesforce.com login requires the URL, Username, and Password fields.
    1. By default, Username and Password are added and pre-configured in the Add Connection Fields page as shown in Figure 3.
    2. Click (+) to add a new field, URL. Select the type as STRING.
    3. Click (^) to move the URL field on top of the list, as the order of the list displayed will be the order of the fields in the Endpoint panel.
    4. Click Next. The Add Activities page is displayed as shown in Figure 4.
      Figure 3. Add connection fields
      Add connection fields

Adding activities

In this section, specify the names of the activities in the connector. The order of the activities in this section is maintained in the Studio Activities toolbox. By default, this section displays a single activity entry as show in Figure 4. You can rename or delete this entry. The Starter activities have only data as Output Type.

Figure 4. Add Activities
Add Activities
  1. As you need to poll the created accounts from Salesforce.com, you must create an activity called PollCreatedAccounts. The following fields are displayed as the output of this activity: AccountID, AccountName, BillingAddress, and Phone. In the Add Connector Activities section, specify the following information:
    1. Double-click activity0 and change the name to PollCreatedAccounts and press Enter.
    2. Select the Starter Activity check box to make the PollCreatedAccounts activity a Starter activity.
    3. Create a schema ActivityOutput.xsd, which contains the output fields mentioned in Step 6, as shown in Listing 1.
    4. Add the XML Schema ActivityOutput.xsd to the Studio project.
    5. Click Select Output, a window with the schema in the ActivityOuput.xsd file is displayed. Select the createdAccounts schema and click OK. The Output Type field is populated with the selected schema name.
    6. Click Next.
    Listing 1. ActivityOutput.xsd
    <?xml version="1.0" encoding="UTF-8" ?>
    <schema attributeFormDefault = "unqualified" elementFormDefault = "qualified" 
     targetNamespace = "http://www.approuter.com/schemas/customeconnector/accountfields" 
     xmlns = "http://www.w3.org/2001/XMLSchema">
        <element name = "createdAccounts" nillable = "false">
            <complexType>
                <sequence>
                    <element name = "accounts" maxOccurs = "unbounded" 
                     minOccurs = "0">
                        <complexType>
                            <sequence>
                                <element maxOccurs = "1" minOccurs = "0" 
                                 name = "AccountID" nillable = "false" 
                                 type = "string"/>
                                <element maxOccurs = "1" minOccurs = "0" 
                                 name = "AccountName" nillable = "false" 
                                 type = "string"/>
                                <element maxOccurs = "1" minOccurs = "0" 
                                 name = "BillingAddress" nillable = "false" 
                                 type = "string"/>
                                <element maxOccurs = "1" minOccurs = "0" 
                                 name = "Phone" nillable = "false" 
                                 type = "string"/>
                            </sequence>
                        </complexType>
                    </element>
                </sequence>
            </complexType>
        </element>
    </schema>
  2. The CDK Wizard now has the required information to create the Studio artifacts and orchestrations. A confirmation window is displayed. Click Yes to generate these artifacts and orchestrations.

    The Final Summary page (see Figure 5) gives the summary of the orchestrations that were created and information about the next steps required for connector development.

    Figure 5. Final summary
    Final summary
  3. Click Finish to close the CDK Wizard. The new connector project now opens in Studio.

Two orchestrations are created, PollCreatedAccounts and TestConnection. As the output of the PollCreatedAccounts activity is not discoverable (the "Input/output parameter requires dynamic discovery" check box is not selected in Figure 4), the List Objects and Describe Object orchestrations are not generated. They get generated only for dynamic discovery of the schemas in an activity.


Completing the TestConnection orchestration

The TestConnection orchestration is designed to test the connection to Salesforce.com. After deploying the SFDCPoller connector, you can see a SFDCPoller entry in the endpoint list of Cast Iron Studio. Create a SFDCPoller endpoint, specify the connection details, and click Test Connection in the endpoint panel of the connector. This instantiates the TestConnection orchestration where it receives the values specified, tests the connection to the endpoint, and sends the status of Test Connection as a response.

  1. Click the Project tab and double-click the TestConnection orchestration to open the orchestration (Figure 6).
    Figure 6. TestConnection orchestration
    TestConnection orchestration

    You can extend this orchestration to meet your requirements. In this case, the TestConnection orchestration must process the TestConnectionRequest data received by the Web Service Provide Service activity. This task involves extracting the connection information and using it in a Web Service Invoke Activity to log on to Salesforce.com. It must also handle a login failure. A Send Reply activity returns a message and a boolean value in TestConnectionResponse and signifies the status of the Test Connection request.

  2. As part of completing the test connection orchestration, use the Login operation in partner.wsdl to test the connectivity to Salesforce.com (Figure 7a and Figure 7b).
    Figure 7a. TestConnection complete orchestration
    TestConnection complete orchestration
    Figure 7b. TestConnection complete orchestration
    TestConnection complete orchestration

In this scenario, the TestConnection orchestration is completed using the activities described in Table 1.

Table 1. TestConnection activities
ActivityActivity Name Activity Use
Web Service Provide Activity TestConnection After entering the endpoint details in the Endpoint Panel, click the Test
Connection button. This orchestration is instantiated when this activity receives the endpoint details as TestConnectionRequest and same is passed as a connectionDetails header.
Map Variables Decode Password The Decode Password Configuration function is used to check if the extracted password is encoded. The result is saved in a String variable.
If Encoded If the resultant string variable in the Map Variables activity is not empty or '', it means that the extracted password is encoded.
If > Map
Variables
Map Variables If the password is encoded, replace the extracted password value with the decoded version using the Decode Password Configuration.
Try Login The Try-Catch block gracefully handles errors during the execution. The Invoke Service activity is used for authenticating to Salesforce.com.
CatchAll CatchAll If an error occurs during execution in this block, the execution flows continue from here.
Try > Invoke Service activity Login Service Makes a login request to Salesforce.com
Try > If If Expired Try-If checks if the login credentials have expired.
Try> If > Map
variables and
Try > Else >
Map Variables
Login Failed
Login Successful
Based on the login operation, initialize the respective response to the TestConnectionResponse variable.
Catch> Map
Variables
Login Failed An error during the execution of the activity in Try block initializes a proper error response to the TestConnectionResponse variable.
Send Reply Send Reply The initialized TestConnectionResponse is sent as a connector activity response.

Completing the PollCreatedAccounts orchestration

Figure 8 displays the template orchestration created by the CDK. The Starter activity orchestration always has the Invoke Service Activity as the last activity in the orchestration, which is preconfigured. You can use a combination of operations available in Salesforce.com to implement your custom starter or poller activity. Once the orchestration is designed and built, ensure that you map the callbackURL element received as a part of the header in the Provide Service activity to the optional parameter location of the Invoke Service Activity.

Figure 8. PollCreatedAccounts orchestration
PollCreatedAccounts orchestration

You can use Login, Query Objects, and Update Objects web service operations of Salesforce.com for a custom implementation of the PollCreatedAccounts Starter activity, as shown in Figure 9.

Figure 9a. PollCreatedAccounts complete orchestration
PollCreatedAccounts complete orchestration
Figure 9b. PollCreatedAccounts complete orchestration
PollCreatedAccounts complete orchestration

In this scenario, the PollCreatedAccounts orchestration is completed using the activities described in Table 2.

Table 2. PollCreatedAccounts activities
ActivityActivity NameActivity Use
Web Service Provide Activity createdAccounts During every poll cycle, the PollCreatedAccounts orchestration is instantiated by invoking the createdAccounts activity. When you implement a Starter activity, no input is expected. However, the endpoint details are sent to this activity as part of the ConnectionDetails header. Before invoking the services of Salesforce.com, you must log on and get a Session ID.
Map Variables Decode Password The Decode Password Configuration function is used to check if the extracted password is encoded. The result is saved in a String variable.
If Encoded If the resultant string variable in the Map Variables activity is not empty or '', it means that the extracted password is encoded.
If > Map
Variables
Update Password If the password is encoded, replace the extracted password value with the decoded version using the Decode Password Configuration.
Invoke Service Login Makes a login request to Salesforce.com and maps the Session ID, which can be used for further requests to Salesforce.com
Invoke Service Query According to the custom design, every unpolled activity has the value of pollable__c set to "true". So, in every poll cycle, you should query the Accounts records for required fields, which has the value of pollable__c set to "true".
Apply XSLT Extract Account Fields Extract the required fields from QueryResponse and construct XML variable conforming to XML Schema of the Invoke Service activity. This is the variable that will be passed as the output of the PollCreatedAccounts activity
Invoke Service Update Mark the value of pollable__c field of the polled or processed accounts field to "false", as you do not need to process the same record in your next poll cycle.
Invoke Service Invoke Service This is the last activity created by the CDK. You must set a location for the optional parameters to the callback_URL value, available as part of the ConnectionDetails header. Then map the XML variable created as part of Extract Account Fields activity to the input body of this activity.

Deploying the SFDCPoller plug-in connector

On completion of the TestConnection and PollCreatedAccounts orchestrations, the development of the SFDCPoller plug-in connector is completed. Now you must deploy the connector project after which you can use the connector to develop business integration orchestrations in Cast Iron Studio.

Steps to deploy the connector are as follows:

  1. Click the Validate button, as shown in Figure 10, to validate the completeness of the connector project. You will be notified about shortcomings, if any, in a window. You have to resolve them until the validation of the project is successful.
    Figure 10. Validate button
    Validate button
  2. Click File > Publish Connector to Local Repository. The connector gets deployed and the SFDCPoller endpoint is available for use. Optionally, you can also click the green up arrow, as shown in Figure 11, to deploy the connector.
    Figure 11. Publish the connector
    Publish the connector
  3. A message is displayed when the connector project is successfully deployed as shown in Figure 12. Click OK.
    Figure 12. Success message
    Success message
  4. Close Cast Iron Studio.

Testing the SFDCPoller plug-in connector

Now, you can use the SFDCPoller connector in Cast Iron Studio to build business integration orchestrations. You can test the SFDCPoller connector and its PollCreatedAccounts activity by completing the following steps:

  1. Open Cast Iron Studio and create a new project called TestPoller.
    1. Select File > New Project.
    2. Specify TestPoller as the Project Name, as shown in Figure 13.
      Figure 13. Create new project
      Create new project
    3. Click OK
  2. Create the SFDCPoller endpoint.
    1. Click the new endpoint button in the Project tab as shown in Figure 14.
      Figure 14. SFDCPoller endpoint
      SFDCPoller endpoint
    2. Select the SFDCPoller endpoint. A new endpoint with the name of SFDCPoller is created in the Endpoints section of the Project tab, as shown in Figure 15.
      Figure 15. Endpoints section
      Endpoints section
  3. Fill the SFDCPoller endpoint connection parameters and test the connection.
    1. Double-click SFDCPoller in the Endpoints section of the Project tab.
    2. Specify the URL, User Name, and Password to connect to Salesforce.com, as shown in Figure 16.
      Figure 16. Salesforce.com connection details
      Salesforce.com connection details
    3. Click Test Connection. The TestConnection orchestration in the SFDCPoller connector project that you developed earlier is invoked. A message is displayed that reports the status of the test connection.
  4. Configure the PollerCreatedAccounts activity and test it.
    1. Add the PollCreatedAccounts activity to orchestration from the Activities tab as shown in Figure 17.
      Figure 17. PollCreatedAccounts configuration
      PollCreatedAccounts configuration
    2. Click the PollCreatedAccounts activity that was added to the orchestration. Add the SFDCPoller endpoint in the Pick Endpoint.
    3. Select the Configure task in checklist. Complete the following properties, as shown in Figure 18:
      • Poll Interval: 30 seconds
      • Path After URL: pollaccounts1. "Path After URL" is the property used by the CDK to uniquely identify a particular instance of the PollCreatedAccounts activity in the current project. Hence, the value for the Path After URL property must be unique across the TestPoller studio project.
        Figure 18. Checklist - Configure
        Checklist - Configure
  5. Start the orchestration. Go to the Verify tab and start the orchestration as shown in Figure 19.
    Figure 19. Start orchestration
    Start orchestration
  6. The PollCreatedAccounts activity polls Salesforce.com every 30 seconds. Create an Account in Salesforce.com:
    1. Login to www.salesforce.com.
    2. Select the Account tab and click New to create an account.
    3. Specify the details and click Save. The newly created account details are shown in Figure 20.
      Figure 20. Account details
      Account details
    4. In the next poll cycle, the account created above will be polled. Now, the job instance can be seen in the Verify tab. The polled data is displayed in Figure 21.
      Figure 21. Polled data
      Polled data
    5. After the poll cycle is complete, you can see the Account details where the custom field Pollable is not checked, which signifies that the Account was successfully polled as shown in Figure 22.
      Figure 22. Pollable field
      Pollable field

Conclusion

In this article, you learned how to:

  • Investigate the APIs and plan your activities supported by the plug-in connector.
  • Use the CDK Wizard to generate artifacts to develop the plug-in connector.
  • Develop the plug-in connector with a Starter activity.
  • Publish and test the plug-in connector in Cast Iron Studio.

Acknowledgments

The authors would like to thank Sarath K. Ambadas for reviewing and providing valuable suggestions for this article

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=934342
ArticleTitle=Developing a starter activity for plug-in connectors using the WebSphere Cast Iron Studio Connector Development Kit
publish-date=06192013