Services and Operations

Creating a service

Configuring a service

Deleting the Service

Services are sets of operations to process data. They can be applied on documents, be called by another service or a Web service, and so on. An operation can use a number of documents as input and output data. Operations are grouped in business-oriented services. The abstraction concept of services and operations, together with documents, makes it possible to create application forms without necessarily rely on data.

An operation is implemented through a method which takes the form of:

• mapping to COGNITUM resources, attributes, and links,
• initialization of a Workflow process, or
• Java code written by a Java developer. For example, a Useradministration service can include the operations
• updatedata with a User as input. The operation is implemented by a method that maps the User change summary to the COGNITUM data abstraction layer to make the changes in the data source.
• hirenewemployee with a User as output. The operation method starts the Workflow process used to hire someone.
• revokeuser with a User as input. The method is a Java code calling the ESS Open Services API to revoke the user accounts.

In this example, the service integrates the data abstraction layer with the COGNITUM Workflow and with another component of the Identity Management Suite (for example ESS Open Services). The operations share the same documents defined in the Console and use the same interface even though the methods behave differently.

Creating a service

Creating a service is necessary for forms to process data.

In the COGNITUM Console, a click on the New Service toolbar button automatically inserts the new Service item in the tree.

Figure: New service creation

It is necessary to configure the new service, as documented below in “Configuring a service”.

To add a service

1. In the COGNITUM Console tree, click the Services item and click the New Service toolbar button.
2. Check that the new service item is automatically added in the tree. Select it to display the service property view and configure the service operations.

Copying a service

You can save time by doing the following: If you have an existing service that is similar to the new service you want to create, you can start by copying the existing service, and then modify it as needed.

1. In the COGNITUM Console navigation pane, right-click the service you want to copy. On the shortcut-menu click Copy.
2. Click the Services root node of any application in the COGNITUM Console, and on the shortcut-menu click Paste. If a service with the same name already exists in the application, a dialog box prompting you to enter a new service name is displayed.
3. Click OK. A new service is created and its name appears listed in the services table.
4. Click the new service and modify its properties as documented in the section,“Configuring a service”.

Configuring a service

A service is defined with the operations it contains. Configuring a service is necessary:

• once a service is added to the tree, or
• to update an existing service.

Service Definition

A click on a service in the tree gives access to the Definition tab where the label and initialization parameters are set.

Figure: Service definition properties

Name: This is the name of the service. When first created, the Service name must be replaced. A click in the cell allows to enter a new name. The service name must follow the Java naming conventions for classes. It must start with a capital letter, cannot start with a number, cannot contain dashes, spaces, and so on, and can only contain ASCII-7 characters (excluding underscores).

Associated Java Class: It is the Java class that implements the service with the custom operations it may contains. To change the Java class manually, the torch button displays the Choose the Java Class dialog box. A custom Java class can be configured with:

• The Generate button creates a Java class pattern.

The Generate All Services command from the context menu of the Services item in the Console tree makes is possible to launch a bulk generating process: the documents are generated and compiled, and the services are generated and compiled.

• The Edit button launches a text editor displaying the Java class code.
• The Compile button compile the .java file to turn it into a .class file.

Init Parameters: This panel defines the parameters which initialize the service. Input parameters from incoming systems (for example COGNITUM Workflow) may be necessary for custom operations (for example COGNITUM Workflow process model IDs). A click on a line makes it possible to complete the Key, Type, and Value cells (for example a Workflow TasksISupervise resource with a String type and a cwf.TaskISupervise value may be entered here).

Service Operations

The Operations tab allows to configure the operations which define the service process.

Figure: Service operations properties

The tree in the Operations tab lists the operations for the service. A click on Add insert an operation item. A right-click in the tree also gives access to the Add command from the context menu.

By default, the new operation is assigned the Call the Stub Operation method.

Name: This is the name of the operation. When first created, the operation name must be replaced. A click in the cell allows to enter a new name. The operation name must follow the Java naming conventions for methods. It must start with a lower case letter, cannot start with a number, cannot contain dashes, spaces, and so on, and can only contain ASCII-7 characters (excluding underscores).

Parameters: This table lists the instances of the documents used for the operation process. A new line is available automatically when the previous parameter has been entered.

• Name: A custom name to identify the parameter must be entered. Non-alphanumerical characters and blank spaces are prohibited.
• Type: It is the format of the parameter. Choosing the proper type makes the most of the processing services.

Table: Service operation types

Multivalued: This option must be checked when the instance corresponds to a list of objects (for example results returned by a search operation).

• Mode: The data processed by the operation can fuel the process (Input option), be returned by the process (Output option), or both (Input/Output option).

The Implementation area makes it possible to specify the method used by the operation.

Method: There are three method categories. According to the method chosen, The operation parameters must be specified (input and/or output entries). The implementation parameters must be entered accordingly too:

• Standard pre-defined methods are available by default in the COGNITUM Console:
• Call the Stub Operation simulates a fully configured operation with a call to a set of random data, making it possible to test the service without necessary defining the physical layer.
• Read an Entry displays entries from a resource.
• Create an Entry writes entries in the resource.
• Delete an Entry erases entries in the resource.
• Update an Entry modifies existing entries in the resource.
• Search for some Entries launches a search process on resource entries.
• Call Custom Code: A custom Java class can serve as the operation behavior definition.
• Initiate a Workflow Process: This method makes it possible to use the data expected and/or returned by a COGNITUM Workflow process.

When the operation is properly set, another service operation can be selected in the list of the service Operations tab for similar configuration.

Once the service operations are done, a click on the Apply button validates the service.

In the Console tree, a right-click on the Services item gives access to the Generate All Services command to ensure the implementation of the services developed for the application.

Operation Standard Method

When the method is a standard one, the Implementation area requires additional properties.

Figure: Operation standard method

• Resource: It is the application resource which is mainly concerned by the process. A click on the list box makes it possible to select on of the resources available for the application.
• Mapping: The Mapping table defines how the document, providing/expecting data for the operation, is mapped on the resource. It is necessary to bind the operation and the document structure with the data layer. The mapping parameters set on the operation level overwrites the default mapping parameters specified on the documents properties level.
• Resource: To select a resource, a click on the Resource cell gives access to the application resources.
• Attribute/Link: A click on this cell makes it possible to choose an attribute or a link already created for the application.
• Document Property: The document property is the result expected from the operation. It can be selected from the Document Property Selection dialog box displayed with a click on the picker button. It can also be entered as the document instance and the property concerned by the mapping.

Figure: Document Property Selection box

To configure a standard service

1. In the COGNITUM Console tree, select the service you want to configure.
2. In the Definition sub tab, fill in the Name box with the label you want to give to the selected service. Enter a label that starts with a capital letter only.
3. In the Associated Java Class area, choose the torch button. In the Choose the Java Class dialog box, click Default Class Name and OK.
4. Choose the Operations tab. In the tab tree, select an operation, and click Add to insert one.
5. Once you have selected an operation in the tab tree, fill in the Name box with the label you want to give to the operation. Do not enter a label that starts with a capital letter.

6. In the Parameters list, complete the instances of the documents used for the operation process. Click a line and :

7. fill in the Name cell with a custom name to identify the parameter

8. In the Type cell, select the format of the parameter
9. Select the Multivalued option when the instance corresponds to a list of objects,

10. Select the Mode option whether the instance will fuel the process or be returned by the process.

11. In the Implementation area, choose:

12. Read an Entry to display entries from a resource,

13. Create an Entry to write entries in the resource,
14. Delete an Entry to erase entries in the resource,
15. Update an Entry to modify existing entries in the resource, or

16. Search for some Entries to launch a search process on resource entries.

17. In Resource, select the application resource mainly concerned by the process.

18. When necessary, change the default mapping parameters in the Mapping table. You can modify how the resource attributes are mapped to the document properties:

19. Click the Resource cell to select an application resource.

20. Click the Attribute/Link cell to choose an application attribute or link.

21. Populate the Document Property cell with the mapping result. A click on the cell picker displays the Document Property Selection dialog box.

22. In the Operations tab tree, you can click Add to insert another operation. Configure it.

23. Click Apply.
24. Back into the Definition tab, choose Generate

Operation Workflow-related method

When the method is a Workflow-oriented one (Initiate a Workflow Process method), the Implementation area shows:

• Process Model ID: It is the identifier of the Workflow process concerned by the operation. The process model ID must be selected.
• Mapping: After selecting the process model, the mapping table shows the process level folder attributes set in the Edit mode while defining the process in Studio. You can map these folder attributes with the document properties used by the service operation.
• Document Property: The document property is the result expected from the operation. It can be selected from the Document Property Selection dialog box displayed with a click on the picker button. It can also be entered as the document instance and the property concerned by the mapping.

Figure: Document Property Selection box

To configure a Workflow-oriented service

1. In the COGNITUM Console tree, select the service you want to configure.
2. In the Definition sub tab, fill in the Name box with the label you want to give to the selected service. Enter a label that starts with a capital letter only.
3. In the Associated Java Class area, choose the torch button. In the Choose the Java Class dialog box, click Default Class Name and OK.
4. In the Init Parameters area, complete the Key, Type, and Value cells with input parameters from the COGNITUM Workflow (for example a Workflow TasksISupervise resource with a String type and a cwf.TaskISupervise value).
5. Choose the Operations tab. In the tab tree, select an operation, or click Add to insert one.
6. Once you have selected an operation in the tab tree, fill in the Name box with the label you want to give to the operation. Do not enter a label that starts with a capital letter.

7. In the Parameters list, complete the instances of the documents used for the operation process. Click a line and :

8. Fill in the Name cell with a custom name to identify the parameter

9. In the Type cell, choose the format of the parameter
10. Select the Multivalued option when the instance corresponds to a list of objects

11. Select the Mode option whether the instance will fuel the process or be returned by the process

12. In the Implementation area, choose Initiate a Workflow Process.

13. In Process Model ID, select the Workflow process concerned by the operation.

14. In the Mapping table, specify how the process model is mapped on the document properties for this operation:

15. Click the Folder Attribute cell to choose an attribute or a link of the Workflow process folder.

16. Populate the Document Property cell with the mapping result. A click on the cell picker displays the Document Property Selection dialog box.

17. In the Operations tab tree, you can click Add to insert another operation. Configure it.

18. Click Apply.
19. Back into the Definition tab, choose Generate.

Operation Custom Method

When the selected method type is Call Custom Code, the Operations tab requires no further parameters. However, in the Definition tab, the custom Java class must be specified.

Figure: Operation custom method

The operation method, implemented through a custom request, is defined by the Java class selected in the Definition tab.

To configure a custom service

1. In the COGNITUM Console tree, select the service you want to configure.
2. In the Definition sub tab, fill in the Name box with the label you want to give to the selected service. Enter a label that starts with a capital letter only.
3. In the Associated Java Class area, choose the torch button. In the Choose the Java Class dialog box, select the custom Java class which defines the service and click OK.
4. Choose the Operations tab. In the tab tree, select an operation, or click Add to insert one.
5. Once you have selected an operation in the tab tree, fill in the Name box with the label you want to give to the operation. Do not enter a label that starts with a capital letter.

6. In the Parameters list, complete the instances of the documents used for the operation process. Click a line and :

7. fill in the Name cell with a custom name to identify the parameter, —in the Type cell, choose the format of the parameter, —check the Multivalued option when the instance corresponds to a list of objects,

8. choose the Mode option whether the instance will fuel the process or be returned by the process.

9. In the Implementation area, choose Call Custom Code.

10. Click Apply.
11. Back into the Definition tab, choose Generate.

Copying a document service operation

Within a service, you can copy/paste existing service operations to make it easy to define similar operations for the same service.

1. In the COGNITUM Console navigation pane, select the service.
2. In the service dialog box, right-click the service operation you want to copy. On the shortcut menu click Copy.
3. Right-click inside the service operations pane. On the shortcut menu click Paste. A copy of the service operation appears and its name is distinguished with a numerical suffix.
4. Repeat the procedure with any other service operation you want to copy.

Deleting the Service

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

The Delete Service message box pops up. Choosing Yes validates the deletion. COGNITUM automatically updates the services list when the service is deleted.

To delete a service

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

Understanding Documents and Services

Building document & services during resource creation

The resource creation wizard incorporates all steps to create documents and services.

In all cases where modifications occur on the resource definition, manual document building and service generation are needed to keep the documents definition accurate with the resource definition.

Building document based on a resource

You can create a new document based on a resource by using the resource right-click menu, which is described below.

1. In the COGNITUM Console navigation pane, right-click the resource you want to use as the basis for your document.

Figure: Build Document context menu.

1. In the contextual menu, click Build Document. A New Document and Associated Object wizard starts. The fields are prefilled with default values.

Figure: New Document and Associated Object wizard.

1. If you want to generate a service with CRUDs operations, check the Create Standard Operations and Associated Forms check box (it is selected by default). Select the view listed under the Forms Definition section in order to add the generated forms to. Click OK.
2. If the document specified with the name field is already present, A dialog box is displayed asking to replace the existing document.

Figure: Document replace confirmation dialog.

1. If you want to replace the existing document with the one you are creating, click Yes else click No. During the document building process the wizard creates or modifies linked Documents, Services and Forms. It will display the same dialog box asking to replace document, service and forms respectively. If you select the check Do not ask me again, it will save the current preference and apply it for others without asking again.

1. The wizard starts the CRUDs service creation process.
2. A new dialog box is displayed: Do you want to generate the service?

Figure: Generate Service confirmation dialog.

1. If you want to generate the service, click Yes. It will create and compile a Java Class template.
2. A new dialog box is displayed: Do you want to set the permissions now?

Figure: Set Permissions confirmation dialog.

1. If you want to set permissions now, click Yes. A Manage Permissions dialog box is displayed.

Figure: Manage Permissions dialog.

1. Select the Roles for which you want the permissions to be applicable.
2. Set permissions under the appropriate tabs for Resources, Operations, and Forms. When you are done click OK.

Building service based on a document

You can create a CRUDS service based on a document by using the document right-click menu, which is described below.

1. In the COGNITUM Console navigation pane, right-click the document you want to use as the basis for your service.

Figure: Build Service context menu.

1. In the contextual menu, click Build Service. A New Document and Associated Object wizard starts. The fields are prefilled with default values.

Figure: New Document and Associated Object wizard.

1. Click OK. The wizard starts the CRUDs service creation process.
2. A dialog box is displayed asking: Do you want to generate the service? Click Yes to generate the service.
3. A dialog box is displayed asking: Do you want to set the permissions now? Click Yes to set permissions.

Generating documents

You can generate documents by using the document right-click menu, which is described below.

This option generates and compiles all documents.

Generating all documents:

1. If you want to generate all documents:. in the COGNITUM Console navigation pane, right-click the Documents item in console tree.

Figure: Generate All Documents context menu.

1. In the contextual menu, click Generate All Documents. The documents generation process starts.

Figure: Document generation dialog.

1. A confirmation message will be displayed after the generation of the documents.

Figure: Generate Document confirmation dialog.

1. Click OK.

Generating Individual document:

1. If you want to generate one document: in the COGNITUM Console navigation pane, right-click the document you would like to have generated.

Figure: Generate Document context menu.

1. In the contextual menu, click Generate. The document generation process starts.

Figure: Document generation dialog.

1. A confirmation message will be displayed after the generation of the document.

Figure: Generate Document confirmation dialog.

1. Click OK.

Generating Documents after resource update:

1. If you update any resource or its attributes: the associated document is preceeded by a “*” in the COGNITUM Console navigation pane, which indicates that it needs to be generated.

Figure: Document need to be generated indication.

1. Update the associated documents for the corresponding changes in resource.
2. You can either generate all or generate the individual documents.

Generating services

You can generate a service by using the service right-click menu, which is described below.

When generating services, the documents and the services are generated and compiled.

Generating all services:

1. If you want to generate all services: in the COGNITUM Console navigation pane, right-click the Services item in console tree.

Figure: Generate All Services.

1. In the contextual menu, click Generate All Services. The services generation process starts.

Figure: Service generation progress dialog.

1. The confirmation message will be displayed after the generation of the services.

Figure: Generate Service confirmation dialog.

1. Click OK.

Generating Individual service:

1. If you want to generate one service: in the COGNITUM Console navigation pane, right-click the service.

Figure: Generate Service context menu.

1. In the contextual menu, click Generate. The service generation process starts.

Figure: Service generation progress dialog.

1. The confirmation message will be displayed after the generation of the service.

Figure: Generate Service confirmation dialog.

1. Click OK.

Generating Services after resource/document update:

1. If you update any resource, its attributes or the corresponding document: the associated service is preceeded by a “*” in the COGNITUM Console navigation pane, that indicates that it needs to be generated.

Figure: Service needs to be generated indication.

1. Update any associated documents for the corresponding changes in resource/document.
2. Update the associated services for the corresponding changes in resource/document.
3. You can either generate all or generate each individual service.