Documentation Center

Deploying Custom Components

In general, components cannot be executed outside of WorldServer. (However, it is possible to create a testing harness for components.) Components are designed to run within WorldServer and to be controlled by WorldServer. Within WorldServer, you can access the components in their specialized areas. For example, if you create a new automatic action, you can include it while defining workflows, and then have it used during the execution of a project. However, the component must first be installed into the WorldServer environment.

Here are the steps for installing a new custom component:
  1. Create a WorldServer component deployment descriptor for your components.
  2. Create a component archive (ZIP file) containing the component classes and all of their non-WorldServer library dependencies.
  3. Use the WSComponentManager or WorldServer UI to deploy the component.

Component Descriptors

Component descriptors are XML documents that provide WorldServer with the information needed to identify and register the components being uploaded. This information is stored in a file named desc.xml. The basic format of this document is shown below.

<components>

<!--
SDK-based components are self-describing. Only the class name is required for them to be properly handled, unlike the legacy implementations. You should feel free to provide comments like this to describe each component as desired. Note that this is a departure from the old desc.xml.
     -->

<!--
Use the auto_action tag to identify an automatic action component. Each automatic action should have a separate tag entry. The name of the automatic action will be retrieved from the implementation class. Please make sure that each automatic action is defined with a unique name since this is how the user will identify it.
    -->

<auto_action class=" "/>

<!--
Use the ais_trigger tag to identify an AIS trigger component. Each AIS trigger should have a separate tag entry. The name of the AIS trigger will be retrieved from the implementation class. Please make sure that each AIS trigger is defined with a unique name since this is how the user will identify it.
    -->

<ais_trigger class=" " />
<!--
Use the tm_services tag to identify the class for the new TM services implementation. Note that this is a singleton component, meaning that there can only be one implementation active within the system. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<tm_services class=" " />

<!--
Use the tm_repair tag to identify the class for the new TM repair implementation. Note that this is currently a singleton component, meaning that there can only be one implementation active within the system. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<tm_repair class=" " />

<!--
Use the authenticator tag to define the new user password authentication implementation. Note that this is a singleton component, meaning that there can only be one implementation active within the system. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<authenticator class=" " />

<!--
Use the connector tag to identify a connector component. Each connector should have a separate tag entry. The name of the connector will be retrieved from the implementation class. Please make sure that each connector is defined with a unique name since this is how the user will identify it.
    -->

<connector class=" " />

<!--
Use the ui_hooks tag to identify the class for the new UI hooks implementation. Note that this is a singleton component, meaning that there can only be one implementation active within the system. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<ui_hooks class=" " />

<!--
Use the word_breaker tag to identify a word breaker component. Each word breaker should have a separate tag entry. The name of the word breaker will be generated automatically based on the language that the implementation is to support. Only one implementation will be allowed in the system for a given language. The most recent one added will be accepted.
    -->

<word_breaker class=" " />

<!--
Use the word_stemmer tag to identify a word stemmer component. Each word stemmer should have a separate tag entry. The name of the word stemmer will be retrieved from the implementation class. Please make sure that each word stemmer is defined with a unique name since this is how the user will identify it.
    -->

<word_stemmer class=" " />

<!--
Use the servlet tag to identify a servlet component. Each servlet should have a separate tag
entry. The name of the servlet will be retrieved from the implementation class. Please make
sure that each servlet is defined with a unique name since this is how the user will identify
it. The name will also be used to identify the servlet in the access URL. The access URL is
defined as follows:

http://<WorldServer URL>/ws-legacy/ws_ext?servlet=<servlet name>&token=[provide token]
    -->

<servlet class=" " />

<!--
Use the filter tag to identify a filter component. Each filter should have a separate tag entry. The name of the filter will be retrieved from the implementation class. Please make sure that each filter is defined with a unique name since this is how the user will identify it.
    -->

<filter class=" " />

<!--
Use the tm_services tag to identify the class for the new TM services implementation. Note that this is a singleton component, meaning that there can only be one implementation active within the system. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<tm_services class=" " />

<!--
Use the notification_services tag to define the notification services implementation to be used by WorldServer. The active implementation will be the last one uploaded, so please make sure you do not attempt to load multiple implementations, else there may be confusion as to which one is being used.
    -->

<notification_services class=" " />

</components>

If you are already accustomed to creating WorldServer components, the descriptor file shown above may seem familiar. However, there are some important differences to understand in order to define component entries properly. The entries above will work only for components developed against the SDK. Entries for legacy custom components will require additional information to be specified in the component entries. For instance, the auto_action tag required "name", "description", and "version" attributes to be defined in addition to the "class" attribute. This is no longer the case since the SDK-based implementations are selfdescribing. This means that the system will be able to retrieve this information directly from the implementation classes.

SDL realizes that it may take some time for customers to migrate their custom code. For this reason, WorldServer will continue to provide support for components developed against the core APIs in addition to those developed against the SDK. This backward compatibility will not be extended indefinitely, and applies only to the core component framework classes, not the core APIs used within the component implementations. The desc.xml files will support both the former component entries as well as the new abbreviated SDK-based component entries.

It is important to note that you should define each component entry based on whether it was developed from the core framework classes or the SDK framework classes. If the component is based on the SDK, then only the "class" attribute is supported. If you include other attributes in the tag definition, it will cause the deployment to fail. (This is done to prevent confusion regarding the non-use of the extra attribute values.) Similarly, if you do not provide the extra attributes for legacy implementations, the deployment process will fail.

Component description entries are only necessary for the component classes, not for each of their dependencies.

Creating Component Archives

A single descriptor file can serve to identify as many components as necessary. However, all of the referenced component classes must be provided with the descriptor in order for them to be registered successfully. A component archive must be created to contain the descriptor file, all component classes referenced, and all of their non-WorldServer-based dependencies. The component archive is simply a ZIP file containing all of these files. You then use this archive to register and upload the components into WorldServer.

Creating a component archive for your uploadable components is simple, provided that you follow some simple rules:
  • The desc.xml must be at the base of the archive.
  • The classes must be located in the archive under the proper Java package structure. The base directory of the archive is to be considered the root of the classpath.
  • There cannot be any JAR or ZIP libraries in the archive. This will not be handled appropriately. In order to use such libraries, you must either expand them out completely in your archive or have them added to the classpath of the WorldServer installation.

Deploying the Components

Once you have constructed your component archive, you are ready to deploy your component. You have two options for doing this. The traditional way is to do this through the WorldServer UI. Navigate to the Customization page (Management > Administration > Customization.

Click the Add button. (It does not really matter which custom component type is currently selected.) This dialog window is displayed:

Click Browse. Locate your archive, and click OK. This will upload your archive and register each component referenced in the desc.xml file, provided that there are no issues. You can then check through the different component types to verify that your components were successfully loaded.

Alternatively, you can upload your components using the WSComponentManager class. The WSComponentManager provides a deployComponent() method that can be called programmatically. In addition, the WSComponentDeploymentCommand can be called as a command-line utility.

java com.idiominc.wssdk.component.WSComponentDeploymentCommand <username><password><component archive path>

When you use the WSComponentDeploymentCommand utility, messages that would be displayed in the UI will instead be written to standard out.