The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
You can use the Service Link Adapter Development Kit (ADK) to develop Service Link adapters. The ADK is the set of components that allow the production of adapters for the Service Link subsystem of Service Catalog. Service Link provides external communications for Service Catalog and provides for coordinated externalization of workflow tasks with other systems.
To achieve this communication, Service Link supports installable adapters. Service Link ships with standard adapters, but developers can create other adapters. This chapter describes the process of writing adapters.
For more support on building custom adapter, contact Cisco TAC.
This section describes the installation of the ADK, its structure, compiling adapters, and adapter deployment.
Follow the instructions from Sun or IBM to install the Java Development Kit. Service Catalog is certified with Sun JDK 6 for installation on WebLogic 12.2.1.2 or JBoss 7.1.1, and with IBM Java 1.6 for installation on WebSphere 7.0.0.17.
1. Administrator : Expand the context of the product packages, locate the adk.zip under the image/isee/dist folder, and inform the adapter developer of the location.
2. Adapter developer : Obtain the file adk.zip (or adk.tar.gz) from the administrator.
3. Adapter developer : Expand the ADK package in a local machine, in C:\ADK. It does not have to be the C drive, nor the ADK directory. However, the examples in this chapter use C:\ADK.
After installing the ADK, the following subdirectories exist:
An adapter is a subdirectory in the main ADK structure. After installing, example is one such adapter. Adapter code has to be structured in the following way
In the example provided, only src and deploy exist.
After compiling the files, create a staging directory (see the following sections for a description on how to build adapters). The staging directory can be deleted and recreated with the build procedure later.
Step 1 Create the directory structure as defined above.
Step 2 Create the source and place it in the structure.
Step 3 Create adapter.xml and place it in the deploy directory. For more information, see the Understanding the adapter.xml Descriptor.
Step 4 Optionally add additional libraries and configuration files.
Step 5 Modify build.properties and add your adapter to the adapters line. This configures ANT to look for the created directories.
The compilation steps allow for adding the build to version control, and later compiled before installation.
After creating the adapter, build it by executing:
build.cmd (or ./build.sh for unix systems)
The final product appears under staging/dist/isee.adapters. This file needs to be provided to the administrator for deployment.
To deploy an adapter, the administrator performs the following procedures:
Step 1 Obtain the Service Link custom adapter package. It should be in the form of a zip file.
Step 2 Unzip the adapter to a temporary directory (for example, c:\temp\adapter). This directory is hereinafter referred to as <AH>.
Step 3 Copy the <AH>/adapters/<ADAPTER_NAME>.jar to the deployed “ISEE.war/WEB-INF/lib” directory.
Step 4 Copy the <AH>/lib/* files (if any) to the deployed “ISEE.war/WEB-INF/lib” directory.
Step 5 Copy the <AH>/config/* files (if any) to the deployed “ISEE.war/WEB-INF/classes” directory.
Step 6 Copy the <AH>/udk/* files (if any) to the deployed “ISEE.war/WEB-INF/classes” directory.
Step 7 If the custom adapter is not developed internally using the Adapter Development Kit, obtain the adk.zip from the "<ServicePortal_Software_Dir>/adk" folder, where <ServicePortal_Software_Dir> is the extracted software image of the Service Catalog application. Extract the adk.zip to c:\adk (for Windows) or /opt/adk (for UNIX/Linux). This directory is hereinafter referred to as <ADK>.
Step 8 Set the JAVA_HOME environment variable if it is not already configured in the environment.
Step 9 Open a command window and cd into the <ADK>/lib folder. Execute adapter_dbinstaller.sh or adapter_dbinstaller.cmd as appropriate to your environment. Use --help or -? as the argument to the adapter installer to see the list of required input arguments. When prompted for the Adapter Deployment Descriptor file, enter the xml file name under the <AH>/deploy directory with the full path (for example, /opt/<AH>/deploy/custom_adapter.xml).
Step 10 For each udk file that was installed (Step 6), add the file’s name to the “UDConfig” property inside the integrationserver.properties file. The UDConfig property is a comma-delimited list of all udconfig files. Append the adapters udconfig files to this list.
Step 11 Start the Service Catalog and Service Link servers. Verify the new adapter exists.
An adapter is the vehicle by which Service Link connects with external systems (often referred as third-party systems). Adapters are composed of three pieces:
The inbound adapter manages incoming communications into Service Catalog. It processes the XML messages coming into the system. There are two types of inbound adapters: pollers and listeners. A poller is a thread that periodically wakes up and looks for incoming messages, while a listener waits and is awakened by an external event. An example of a poller is the inbound file adapter, which needs to periodically check for messages. An example of a listener is the HTTP adapter which waits until an HTTP XML event is posted.
Outbound adapters manage the XML messages coming out of Service Catalog. There is only one type of outbound adapter.
An agent is a logical element that protects service designers from having to know all the complexities of adapter and connection properties. And agent defines an inbound adapter and an outbound adapter. The inbound adapter is optional and can be specified as “Auto complete”. “Auto complete” is a mode whereby the system does not need a reply from a third party for the workflow to proceed, and is mostly associated with unreliable, or shoot-and-forget protocols, such as an email-based system. The administrator configures agents and their associations with adapters for the service designers to use.
In addition, XML transformations can be applied to messages before they go to a third-party system, or after they are received from a third-party system and delivered to Service Link.
The message system uses a common XML dialect known as nsXML, which is a schema that defines the valid XML that Service Link can process or produce. nsXML currently consists of six operations:
When outgoing, Service Link can transform these operations to a destination. The same is true for incoming messages, and the XSL transformations can convert the external format into the nsXML dialect.
For more information about nsXML operations, see Understanding Communication Message Content and Structure.
The adapters are of two types:
Transport adapters are specific to a given transport, such as HTTP, file, JMS, or some proprietary network socket implementation.
Application adapters have an element of transport but are better understood by the specific third-party application, such as Remedy and Siebel. In many cases native APIs are provided through jars. In this version of Service Link, transport adapters cannot yet be extended to create application adapters.
Agents may use different adapters for inbound and outbound messages.
In order to connect to third-party systems, adapters may expose connection properties that the Service Link module exposes to administrators. They are described in the XML deployment descriptor, and their values can be retrieved by the java code to a well established API.
This section illustrates how to implement a simple adapter. The example adapter is a file adapter that communicates with the external world.
First, create the adapter’s directory structure. In the ADK directory structure, create a directory named simple, and create the following directory structure under it:
Figure 6-1 Directory Structure
Under src notice the source package representing the java package com.newscale.is.adapter.filetest. Any other package can be used, but this example uses this one.
Secondly, create the outbound adapter class. The name is FileOutboundAdapter and this class file should be placed in the package described in step one. Its skeleton is shown below, without the implementation of the methods.
To create an outbound adapter, the class needs to extend the class com.newscale.is.adk.base.OutboundAdapter as shown above.
Implement a constructor that receives a com.newscale.is.adk.AdapterContext as a parameter. The recommended way to implement this constructor is also shown above: calling the super constructor.
Implement the initiate method as shown above. This method is called when an agent using the adapter is started. If this method is empty, you can omit it.
Implement the processMessage method. This method is called when a message is ready to be sent. If a transformer is specified in the agent, the transformer has transformed the message.
Implement the terminate method. Call this method is when the agent stops. If this method is empty, you can omit it.
Implement the commit method. Call this method when the agent is about to complete its transaction. If this method is empty, you can omit it. This method is used so that a transaction can be started in the processMessage, and later completed.
Implement the rollback method. This method is called when the agent is about to rollback its transaction. If this method is to be left empty, it can be omitted. This method is used so that a transaction can be started in the processMessage, and later recalled.
For more information about transaction support, see Configuring Transaction Notification.
In our case, the file outbound class writes a file with the contents of the xml. To achieve that, first set up a variable that keeps the file name where the file is stored. For this purpose, use the agent properties.
When the string is received, writing it to the file is trivial.
Of course, this code has been oversimplified for the sake of explanation.
The skeleton for our inbound adapter is as follows:
The semantics of the methods are just like the ones in the outbound adapter. The only exception is the receiveMessage method. The receiveMessage method is called periodically in the case of a poller adapter. If data is found, then the method returns a valid xml in third-party format. If no data is found, null is returned. The code for the inbound adapter is as follows (just like the outbound adapter, the initialization is done with the correct parameters):
Processing of the file is done as follows:
A listener adapter is created by virtue of an ad-hoc process. Two classes are in play: the inbound adapter class, and an actual receiver class, like a servlet. The receiver class is required to obtain the channel ID. The receiver class locates the InboundAdapter class as follows:
The inbound adapter has a method called receiverProcess that should be called with the message, or an object whose toString() method returns the text of the message. The example does not provide a listener inbound adapter.
Once the two adapters are done, the exception handler needs to be implemented. In our case it is a very simple class, where all we do is output the error. The complete class is shown here:
Transaction support has been provided to the adapters so that agents get notified before they undo their own transactions. The methods commit and rollback have been added for that purpose.
Note No logic code should be added to these methods, as the system is in the middle of committing or rolling back a transaction. These methods should only rollback or commit their resources.
To track resources to be committed or rolled back, an adapter can use this common technique:
Create a static map. Once the processing method is called (either processMessage or receiveMessage) the method can add:
The adapter descriptor contains information for the deployment of the adapter and its properties.
The adapter schema is as follows:
description : Description of the adapter
inbound-class : Absolute class name of inbound adapter
outbound-class : Absolute class name of outbound adapter
exception-class : Absolute class name of exception handler for this adapter
poll-interval : Poll interval (applicable for “poller” type adapter) in milliseconds
max-retry : Max number of retries in case of message failure
name : Name of the adapter property
default-value : Default value for the property
is-required : Whether this is a mandatory or optional property. Valid values are “true” or “false”
property-type : The type of property. Valid values are “string” for now.
property-presentation : Valid values are “text” and “password”
This section describes the details of the communication message content and structure. The message content is encapsulated in XML documents which are sent between Service Catalog and third-party systems over various carrier protocols such as HTTP, SOAP, or JMS. For easier understanding of the structures and substructures of messages, a graphical notation is used.
The outbound \has a top level element message which contains the element “task-started” or “task-canceled”. The inbound document has a top level element message which contains one or many elements “add-comments,” “send-parameters,” or “take-action”. The message tag has a mandatory attribute which is called channel-id and is of type string. It is a unique string value created by Service Link for any outbound message created. The third-party system needs to reply back the message with the corresponding channel-id. This ID has to be carried on both the Service Catalog and third-party system sides.
Figure 6-4 Task Started or Task Cancelled
Task started kicks off an external activity in the third-party system. The design strategy followed for this operation is to incorporate all the information that may be required by the third-party system to execute the task. This element holds all the required details about the task and the requisition it belongs to. It may also contain one or more optional agent parameters. The context element describes the task in context of service delivery plan. This node does not contain values for Requisition-level reviews and approvals.
The requisition element encapsulates all requisition and requisition entry data that can be used for integration purposes when executing an external activity.
This tag encapsulates all the data of one requisition entry that can be used for integration purposes.
The data-values element can have one or more data values comprised of dictionary data. The data-value name indicates the “Dictionaryname.FieldName” and value is the value entered by the user while ordering the service. If the value is a multi-select drop down list, then one data-value element can have multiple values.
|
|
Element which holds all the field elements of the service form. |
|
Specifies if the service is a bid, pricing task or fixed price. |
|
The agent parameter represents the external parameters specified for the agent. It has the Boolean attribute called multi-valued which is either true or false based on whether this parameter has multiple values selected by user. The name represents the name of the agent parameter and value represents its value.