Web Services and Functions

Creating a Web Service

Copying a Web Service

Modifying a Web Service

Deleting a Web Service

Creating a Function

Copying a Function

Configuring and modifying a function

Configure parameters for Web Function

Deleting a Function

Web services are COGNITUM facilities meant to give access and distribute data processed by COGNITUM.

A Web service is a set of associated functions. Functions defined within a Web service are designed for being invoked by any external client. For more information about the functions, see “Creating a function”.

Once created, Web services are stored and accessible on the COGNITUM server. They are invoked through the SOAP protocol or by the long URL method. The HTTP protocol is used to transport both requests and responses.

Creating a Web Service

Creating a new Web service consists in identifying the facility and the access mode.

In the COGNITUM Console, a click on the New Web Service toolbar button displays the New Web Service dialog box.

Figure: New Web service creation

Application: It is the name of the application the Web service is linked to. Another application can be selected in the list box when available.

Web Service Name: It is the name of the Web service as it appears in the COGNITUM Console. It is used to invoke the Web service. Combined with the application name, it is used to create the Uniform Resource Identifier (URI) for the HTTP request required to invoke the Web service. Non-alphanumerical characters and blank spaces are prohibited.

Web Service State on Startup: This list box allows to activate the Web service when the COGNITUM server (re)starts. It also defines the Web service state after its initial creation.

Authorize Web Service Access through HTTP: The check box defines whether the Web service is accessible externally or not.

A click on OK validates the Web service creation. Further descriptive information can be entered with the Edit Description command accessible with a right-click on the Web service in the tree. The Web service description appears as a pop-up window when leaving the cursor on the Web service tree item.

When the Studio generates services for an application, the Refresh command accessible with a right-click on the Services tree item makes it possible to update the services list in the COGNITUM Console.

To add a Web service

1. In the COGNITUM Console, click the New Web Service toolbar button.
2. In the New Web Service dialog box, you can change the Application entry with another application with the torch button when available.
3. In the Web Service Name box, enter the label of the Web service to be used when invoking it in HTTP requests.
4. In Web Service State on Startup, select "Available" when you want the Web service to run when the COGNITUM server (re)starts, or "Unavailable" when you want it to be off.
5. Check the Authorize Web Service Access through HTTP check box to make the Web service accessible externally.
6. Click OK to validate the Web service creation.

Copying a Web Service

A Web service created and configured for an application can be duplicated into the same application, or into another application. This feature allows to bypass the complete Web service creation process, including the associated functions.

The Copy command is accessible from a selected Web service from its context menu or from the Edit menu.

The target Web Services item must be selected before choosing the Paste command from the context menu or from the Edit menu. When the Web service is duplicated within the same application, a message box pops up to give another name for the duplicate.

Parameter changes may prove necessary, as documented in “Modifying a Web service”. Besides, the rights associated to the Web service functions are reset; they must be configured before the copied Web service is available to endusers, as documented in “

Roles

”.

To copy a Web service

1. In the COGNITUM Console tree, select the Web service to copy.
2. Choose the Copy command from the context menu.
3. Select the target Web Services item.
4. Choose the Paste command from the context menu.
5. Update the parameters of the Web service duplicate as required.
6. Update the associated rights in the roles definitions.

Modifying a Web Service

Once a Web service is added to the COGNITUM Console tree, it is ready to be granted functions, as documented in “Creating a function”. Also, the rights associated to the Web service functions must be configured before the Web service is accessible to end-users, as documented in Chapter 12, “Roles”.

Parameters specific to a Web service can be updated at the Web service level. When a Web service is selected in the COGNITUM Console tree, the Definition tab is displayed.

Figure: Web service definition properties

Web Service Name: The name of the Web service can be changed. Non-alphanumerical characters and blank spaces are prohibited.

Web Service State on Startup: The operational status of the Web service when the COGNITUM server (re)starts can be modified.

Authorize Web Service Access through HTTP: The option can be modified to make the Web service accessible externally or not. When activated, the Web service icon in the tree carries the "http" mark.

A click on the Apply button validates the parameters.

To modify the Web service properties

1. In the COGNITUM Console tree, select the Web service you want to modify. The facing Definition tab is displayed.
2. In the Web Service Name box, you can modify the name of the Web service to be used to invoke the Web service.
3. In the Web Service State on Startup list box, you can switch the state of the Web service as COGNITUM server (re)starts.
4. You can uncheck Authorize Service Access through HTTP check box to make the Web service inaccessible externally.
5. Click Apply to validate your changes.

Deleting a Web Service

COGNITUM makes it possible to delete a Web service and the associated functions easily and safely. The Delete command is accessible from a selected Web service context menu.

The Delete Web Service message box pops up. Clicking Yes confirms the deletion. COGNITUM automatically updates the Web services list.

To delete a Web Service

1. In the COGNITUM Console tree or property view, click the Web service you want to delete.
2. Choose Delete from the context menu.
3. Validate the removal in the warning box.

Creating a Function

Functions are executable processes correlated to a Web service. They are meant to be invoked by clients and launch specific actions. They are declared in the COGNITUM Console.

COGNITUM provides basic function types to create custom functions.

Creating a function consists in referencing the Web service invoked and the operation launched by the Web service.

In the COGNITUM Console, a click on the New Function toolbar button displays the New Function dialog box.

Figure: New function creation

Application: It is the name of the application the function is linked to. Another application can be selected in the list box when available.

Web Service: This is the Web service the function applies to. Another service can be selected in the list box among the Web services of the selected application, when available.

Function Name: This is the name of the function as it is displayed in the COGNITUM Console. It is used to invoke the function. Non-alphanumerical characters and blank spaces are prohibited.

Function Type: This area identifies the main function types available for the creation of a function:

• Predefined Type: The functions may be predefined type functions. The facing box lists the predefined functions available:
• Call Chainer: This function type allows to bind function calls. Such a function type allows to call other functions within any Web service of a same application.
• File Writer: This function type writes and stores all call parameters in a text file. The URL of the generated file is returned as a response.
• Mailer: This function type allows to send an e-mail.
• URLMapper: This function type allows to create a function that connects a URL. When this type of function is requested, an HTTP connection is launched towards the URL specified in the Parameters Values column.
• XSL Transformer: This function type transforms into XML the function call parameters. The XSL transformation parameter is an initialization parameter. This function allows to transform XML data with an XSL stylesheet. This function can be associated with the COGNITUM Entry Requester one as this function returns XML data as a result.
• COGNITUM Application Requester: This function provides the name of the current COGNITUM application the predefined type is used in.
• COGNITUM Entry Requester: This function type allows to make an LDAP request on a directory.
• COGNITUM Entry Updater: This function allows to update a directory entry. Create, update and delete requests can be submitted onto the related COGNITUM application.
• COGNITUM Structure Requester: This function type allows to perform a request on COGNITUM structures so as to retrieve the applications list. This list includes the views and resources defined for each application.
• COGNITUM Scheduler: This function allows to schedule a job in the Scheduler. The function can only run when a Scheduler is implemented for the application. For more information, see the COGNITUM Scheduler Implementation Guide.
• COGNITUM Scheduler Administration: This function allows to change the state of a job in the Scheduler.The function can only run when a Scheduler is implemented for the application. For more information, see the COGNITUM Scheduler Implementation Guide.
• COGNITUM Scheduler Search: This function allows to search jobs in the Scheduler. The function can only run when a Scheduler is implemented for the application. For more information, see the COGNITUM Scheduler Implementation Guide.
• Custom Java Class: A custom Java class can be used as a function type in COGNITUM Web services:
• Java Class: This box can be completed with the name of the Java class. A click on the torch button makes it possible to select a Java class.
• Default Name: A click on this button fills in the Java Class box with its default name.
• Generate the Source File: Selecting this check box allows to create a pattern program displaying the name of the methods to be used, the specific location of the values to be entered and comments.

Parameters Names/Values: This table lists the parameters which are bound to the selected predefined function type or the Java class. They specify the function behavior.

For both predefined and custom function types, default parameters are displayed automatically. They just need to be configured in the Parameters Values column.

• Init parameters are displayed in red bold style.
• Mandatory call parameters are in bold style and end with an asterisk.
• Optional call parameters are in bold style.

Additional parameters can be entered in the Parameters Names and Parameters Values columns too.

A click on OK creates the function. Further descriptive information can be entered with the Edit Description command accessible with a right-click on the function in the tree. The function description appears as a pop-up window when leaving the cursor on the function tree item.

The associated rights must be configured before the function is accessible, For more information, see “

Roles

”.

To add a function into a Web service

1. In the COGNITUM Console tree, select a Web service item and click the New Function toolbar button.
2. In the New Function dialog box, you can change the Application entry in the corresponding list box when available.
3. In Web Service, select the related Web service for the selected application, when available.
4. In the Function Name box, enter the label of the function.
5. In the Function Type area, make the function a predefined one or a Java custom one.
6. In the Parameters/Values table, set the values of the retrieved parameters and/ or add custom parameters for the function behavior.
7. Click OK.
8. Update the associated rights in the roles definitions.

Copying a Function

A function created and configured for a Web service can be duplicated into another Web service, whether in the same application or in another one. This feature allows to bypass the complete function creation process.

The Copy command is accessible from a selected function from its context menu or from the Edit menu.

The target Web service item must be selected before choosing the Paste command from the context menu or from the Edit menu. When the function is duplicated within the same Web service, a message box pops up to give another name for the duplicate.

Parameter changes may prove necessary, as documented in “Configuring and modifying a function”. Besides, the rights associated to the copied function are reset; they must be configured before the function is available to end¬users, as documented in “Roles”.

To copy a function

1. In the COGNITUM Console tree, select the function to copy.
2. Choose the Copy command from the context menu.
3. Select the target Web service item.
4. Choose the Paste command from the context menu.
5. Update the parameters of the function duplicate as required.
6. Update the associated rights in the roles definitions.

Configuring and modifying a function

The context parameters of a function can be modified at any time:

• Once a function is added to a Web service
• To update an existing function

When a function is selected in the COGNITUM Console tree, the Definition tab is displayed.

Figure: Function definition properties

Function Name: The name of the function can be modified provided it does not contain non-alphanumerical characters or blank spaces.

Type: This informative line indicates of which type the function is.

Account: The list box displays the accounts available for the function execution. The aliases displayed in the list box are those defined for the application in the Account tab. For more information, see “Account library”.

Selecting an account for a function is useful when, for example, a user is authorized to execute an entry update function such as the COGNITUM EntryUpdater while he is not authorized to perform any updates in the directory. Selecting an account for the function allows to update the entry through the function alias. The user only has to launch the function and the entry update is performed with the account declared in the Account list box.

Associated Java Class: When the function is a Java class, this area is displayed. To change the Java class, the torch button displays the Choose the Java Class dialog box. A custom Java class can be configured:

• The Edit button launches a text editor displaying the Java class code. The editor used to open the source file can be selected with the Editor command from the Tools => Preferences menu.
• The Compile button compiles the .java file to turn it into a .class file.

Parameters Names/Values For both predefined and custom function types, the table displays the parameters defined for the function. A click in any cell of the table allows you to modify the corresponding entry, as described in “Creating a function”.

A click on the Apply button validates the function changes.

To configure the function properties

1. In the COGNITUM Console tree, select the function you want to modify.
2. In the Function Name box, you can modify the physical name of the function.
3. In the Account list box, select the account to use to execute the function.
4. When the function is of JAVA_CLASS type, the Java class torch button makes it possible to select another Java class. Click the Edit button to edit the Java class code and modify it. Click the Compile button to compile the .java file.
5. In the table, change the parameter(s) and/or the value(s) of the function.
6. Click Apply to validate your changes.

Configure parameters for Web Function

When the function is a Java class function, you can define input parameters and result for that function using COGNITUM Console itself without need to edit and then compile Java class.

Create web function with function type as Custom Java Class. See Creating a Function to know how to create web function.

Figure: New Function

When a newly created function is selected in the COGNITUM Console tree, the Definition tab is displayed.

Figure: Definition Tab

Define Input Parameters

Input parameters have these properties which can be set from COGNITUM Console,

1. Parameter Name: name of the parameter
2. Type: type of the parameter i.e. any accessible Java class. Console provides some commonly used Java class those can be selected from the drop-down list as shown below,

If you want to define a type which is not included in default types list, select the last entry which is a blank as shown below.

When you select last entry from types drop down list, it becomes editable. You can type accessible fully qualified class name as parameter type as shown below,

1. Default Value: When type of parameter is String, you can define a default value for that parameter. When function caller don’t provide any value to this parameter, default value will be used at the time of function invocation.
2. Multivalued: Define whether parameter is monovalued or multivalued. When checkbox is selected, the type of the parameter is set as Array of selected type as shown below. For example, when type is java.lang.String and multivalued is selected, the resulting type of parameter becomes java.lang.String[].
3. Mode: Possible modes of a parameter are as shown below,
4. Initialization: Parameter must be initialized with the default value.
5. Mandatory: Parameter value must be provided when invoking the function when default value is not given in Console.
6. Optional: Parameter value in function call is optional.

Define Result Parameter:

A web function can have result parameter or none. There can only be single result parameter for a web function.

Figure: Result parameter

Result parameter has following properties,

1. Name: Name of the result parameter
2. Type: Java type for the result parameter.
3. Multivalued: Whether or not parameter is multivalued.

Type and Multivalued properties work in similar manner to those of type of Input parameter.

Remove defined parameter

To remove any input or result parameter, delete the parameter name and press Enter. The parameter row gets deleted.

Saving the changes

When you are done with defining input and result parameters for web function, click on Apply. Mapped custom java file gets updated and compiled. If no error occurs, message box with message, “The compilation succeeded” appears.

Figure: message

Figure: modify function java class

Deleting a Function

COGNITUM makes it possible to delete a function easily and safely. The Delete command is accessible from a selected function context menu

The Delete Function message box pops up. Clicking Yes confirms the deletion. COGNITUM automatically updates the Web services list.

To delete a function

1. In the COGNITUM Console tree or property view, click the function you want to delete.
2. Choose Delete from the context menu.
3. Validate the removal in the warning box.