Documents

Creating a document

Configuring a Document with Simple Properties

Deleting a document

Improvements in Documents feature in COGNITUM 7.8.00

Documents are sets of data that are used by COGNITUM forms, processed with COGNITUM services, and displayed according to COGNITUM form definitions.

Documents are abstraction models that exist between the data layer and processes. Documents represent data in a standardized way, whatever the source (COGNITUM data sources or other systems—for example COGNITUM Workflow) and type.

Documents are defined by properties that are:

• Simple: if they match a Java type (e.g. string, integer)
• Composite: if they include sub-properties

The following procedures are described:

Creating a document

Creating a document is necessary to enable forms and services to handle application data.

1. In the COGNITUM Console navigation pane, select the Document root node and then do one of the following:

2. Right-click the Document root node, and on the shortcut-menu select New Document

3. Select File> New> Document
4. Click the New Document toolbar button The New Document and Associated Objects dialog box is displayed.

Figure: New Document and Associated Objects dialog box

1. Enter a name for the Document. Follow the naming convention used for naming Java classes.

2. The document name must start with an uppercase letter, it can include underscores, it cannot contain dashes or spaces and can only contain ASCII-7 characters.

3. The name of a document may start with a package prefix. For example in the Scheduler package includes the scheduler.History, scheduler.Job and scheduler.Alarm documents. A package prefix must also be a valid Java identifier.

1. If you want to generate a service with CRUDs operations, select the Create Standard Operations and Associated Objects check box.
2. Enter a name for the service. Follow the naming convention used for naming Java classes.
3. If you want you can select the Map to Resource option button and then select on a drop-down list the resource you want the service to map to.

1. Click OK.
2. A confirmation dialog box is displayed. Click OK. The CRUDs service is created. (It may take up to ten minutes to create the service.) A dialog box is displayed asking: Do you want to set the permissions now?
3. If you want to set permissions now, click Yes. A Manage Permissions dialog box is displayed.

Figure: Manage permissions dialog box

1. Select the Roles to 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.

It is necessary to configure the new document, as documented in the sections:

• “Configuring a document that contains simple properties”
• “Configuring a document that contains complex properties”

Creating a document based on a resource

You can create a new document based on a resource. There are two similar ways that you can do this. The first way was described in the previous section, and involved selecting the resource in from a drop-down list in the New Document and Associated Object dialog box.

An alternative way is to start by right-clicking the resource, which is described below.

Using the resource right-click menu

1. In the COGNITUM Console navigation pane, right-click the resource you want to use as the basis for your document.
2. On the shortcut menu, click Build Document. A New Document and Associated Object wizard starts. The fields are filled in with default values.
3. If you want to generate a service with CRUDs operations, be sure the Create Standard Operations and Associated Objects check box is selected (it is selected by default). Click OK.
4. A confirmation dialog box is displayed. Click OK. The CRUDs service is created. (It may take up to ten minutes to create the service.)

A dialog box is displayed asking: Do you want to set the permissions now?

1. If you want to set permissions now, click Yes. A Manage Permissions dialog box is displayed.
2. Select the Roles to which you want the permissions to be applicable.
3. Set permissions under the appropriate tabs for Resources, Operations, and Forms. When you are done click OK.

It is necessary to configure the new document, as documented in the sections:

• “Configuring a document that contains simple properties”
• “Configuring a document that contains complex properties”

Copying a document

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

1. In the COGNITUM Console navigation pane, right-click the document you want to copy. On the shortcut-menu click Copy.
2. In the COGNITUM Console, right-click the Documents root node under the application where you want to paste the selected document, and from the shortcut-menu click Paste. If a document with the same name already exists, a dialog box is displayed prompting you to enter a new document name.
3. Click OK. A new document is created and its name appears listed in the documents table.

4. Click the new document and modify its properties as documented in the sections:

5. “Configuring a document that contains simple properties”

6. “Configuring a document that contains complex properties”

Configuring a Document with Simple Properties

Simple documents include basic classes such as strings, integers, and dates. Configuring a simple document is necessary when you:

• Create a new document
• Update a document

Add or modify a property

To add a new property

1. In the COGNITUM Console navigation pane select the document.
2. In the right pane Properties pane, right-click the document root node. In the shortcut menu click Add. A new property node is displayed under the document.

Figure: Adding a new property

Enter or select values for the property under each of these tabs: Definition, Possible Values and Metadata.

Definition Tab

Figure: Simple document property Definition tab

The Definition tab makes it possible to configure the following document properties.

Name: This is the name of the property. The property name must follow JavaBeans naming conventions for properties. It cannot start with a number, cannot contain dashes, spaces, and can only contain ASCII-7 characters (excluding underscores). Moreover, Java keywords are prohibited.

Type: In the Type list box the Java type for the property can be selected.

Table: Property types (part 1 of 2)

Table: Property types (part 2 of 2)

Mandatory: This option can be used to make value assignment compulsory.

Monovalued: When a property is monovalued, it means that the matching attribute can only have one value.

Read Only: This option must be checked when the matching attribute cannot be modified in the portal. The attribute is displayed but it is frozen.

Unique: When the check box is selected the value of the matching attribute cannot be the same for another entry.

Default Values: A property can be assigned default values. The values are used by the COGNITUM application server, provided no value has been previously defined for the attribute. When the matching attribute is called, the values are associated by default. A click on the Add button inserts a line in the Default Values list and a default value option can be entered in the inserted line.

The Possible Values sub-tab makes it possible to associate the property with a number of possible values. The values are used as a rough guide used by the COGNITUM application server to generate the appropriate user interface.

Possible Values Tab

Figure: Simple document property Possible Values tab

No Rule: With this option, the property can take any value fitting its type.

Must belong to: When this option is selected, the facing table can list the values which the property must match. The values can be associated with a specific syntax. The property value displayed in the application and the value stored in the data source may follow distinct formatting rules. Accordingly, COGNITUM deduces the value to display and the value to store in the data source.

A click on a line allows to enter a value expression manually. The cell button can be also selected to display the Choose an Attribute Value dialog box. This dialog box helps specify the possible values of a property very quickly, especially with references to variables and dictionary keys. For more information, see “Choosing an attribute value”.

Foreign key to Property matching: With this option, the value of the property corresponds to the value of a property of one or several Documents or to its DN property. The drop-down list displays Properties of same type.

Foreign key to Resources matching: With this option, the value of the property corresponds to the value of an attribute of one or several resources or to its DN. One of the two following options can be selected, and the property possible values must be specified in the table beneath:

• a DN is an LDAP-specific option which must be chosen when the property value is the DN of the selected resource.
• an Attribute allows that the value of the property is one of the attributes of the selected resource.

Foreign key to Document matching: If the property "type" is a Document itself (for the same or another Document) the foreign key is the respective Document as "type" in definition Tab.

In the table for the foreign keys, a click on the Add button makes it possible to add an attribute of one or several resources which will serve as a possible value. The Resource cells list the resources available, and the Attribute cells help select the one of the related attributes. An attribute can be linked to a number of resources. The picker button in the Filter cells displays the Logical Query Builder dialog box—described in Chapter 3, “Data sources”—where a filter can be added on the returned entries.

Metadata Tab

The Metadata sub-tab makes it possible to specify additional parameters. The document called by the operation provides/expects the data from the mapped resource, as documented in “Service operations”. The default mapping parameters help configure operations consistently.

Figure: Simple document property Metadata tab

Default Mapping: In this area, the following items can be chosen:

• 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 selected resource.

Other In the Other area, the Kind box makes it possible to define the type of the property for the portal to display the corresponding component. The property type can be entered or selected among the predefined ones:

• Password
• Image
• E-mail
• Certificate
• MIME: image/gif
• MIME: image/jpeg

When the property is properly set, another document property can be selected in the Properties list for similar configuration. Once the document properties are done, a click on the Apply button validates the parameters entered in the document Definition, Possible Values, and Metadata tabs.

To configure a simple document

1. In the COGNITUM Console tree, select the document you want to configure.
2. In the facing property view, unfold the document properties tree. When necessary, click Add to insert a new property.
3. In the document properties tree, select a property.
4. In the Definition sub-tab, fill in the Name box with the label you want to give to the selected property. Enter a label that follows JavaBeans naming conventions for properties. The label cannot start with a number, cannot contain dashes, spaces, and so on, and can only contain ASCII-7 characters (excluding underscores). Moreover Java/SDO keywords are prohibited.
5. In Type, select a property format—other than <composite>—that best fits the property processing behavior.

6. Check the following options when necessary:

7. Mandatory to make value assignment compulsory,

8. Monovalued to state that the matching attribute can only have one value,
9. Read Only to make the matching attribute for view only,

10. Unique to state that the matching attribute cannot be the same for another entry.

11. When the document property can be assigned default values, click the first Default Values line and enter a value. Click Add to insert another line, before filling it in.

12. Select the Possible Values sub-tab when you want to associate the property with a number of values. Choose the option for the type of property integrity check:

13. No Rule when you want COGNITUM not to provide for any format for the property.

14. Must belong to when you want to define a list of possible values to match with the property. In the facing list, click the cell button to specify the property possible values quickly.
15. Foreign key to Resources matching to link the property with a resource. The link can be:
16. a DN to link the attribute with the DN of the selected resource, or

17. an attribute to link the property with the attribute(s) of the selected resource. In the list box below, select the attribute of the selected resource to link with the attribute. Click Add to insert a new line.

18. Select the Metadata sub-tab when you want to specify extra data on the property:

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

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

21. In the Properties tree, click Add to insert another property. Configure it as above described.

22. In the Properties tree, using the arrow buttons organize the properties in the order in which you want them to appear in the end-user interface.
23. Click Apply.

Copying a document property

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

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

Additional configuration options

The following sections describe optional configuration tasks for simple documents.

Define a document primary key

If you want, you can define a primary key identifier for a document. The primary key consists of one, or more, document properties you have already created.

Figure: Define a document primary key Definition tab

To define a primary key for a document

1. In the COGNITUM Console navigation pane, select the Document you want.
2. In the right pane, select a Document property you want included in the Document primary key.
3. Under the Definition tab, verify that the property’s Mandatory attribute is selected. If the Mandatory attribute is not selected, select it and click Apply. Only mandatory attributes can be part of a primary key.
4. Repeat step 3 until all properties you want included in the primary key have their Mandatory attribute selected.
5. In the right pane, select the document root node and then select the Definition tab.
6. In the right pane, under Identifier, click a blank row and using the drop-down list select a property you want included in the primary key definition.
7. Repeat step 6 until all of the properties you want included in the primary key have been added.
8. Click Apply.

Define the document display fields

If you want, you can set the fields a document can display in a user interface. The display fields consists of one, or more, document properties you have already created.

Figure: Define document display fields Definition tab

To define the document display fields

1. In the COGNITUM Console navigation pane, select the Document you want.
2. In the right pane, select the Definition tab.
3. In the right pane, under Displayed Properties, click Insert.
4. Using the drop-down list select the property you want displayed.
5. Repeat steps step 3 and step 4 until all of the properties you want to make available for display are included.
6. Click Apply.

Define the default search criteria of a document

You can specify which document fields are searched and which document fields are included in search results.

Figure: Define default search criteria Search tab

To define the document fields that are searched

1. In the COGNITUM Console navigation panel, select the Document you want.
2. In the right panel, select the Search tab.
3. In the right pane, under Criteria, click Insert.
4. Using the drop-down list select a property you want included in the search.
5. Repeat step 3 and step 4 until all of the properties you want to include in searches are included.
6. Repeat step 3 and step 4 until all of the properties you want to make available for searches are included.
7. Click Apply.

To define the document fields that are included in search results

1. In the COGNITUM Console navigation panel, select the Document you want.
2. In the right panel, select the Search tab.
3. In the right pane, under Results, click Insert.
4. Using the drop-down list select a property you want included in search results.
5. Repeat step 3 and step 4 until all of the properties you want in search results are listed.
6. Click Apply

Figure: Define document fields to include in search results

Configuring a document with complex properties

Composite-type documents include properties with sub-properties. Composite properties can have several levels of nested properties. Configuring a composite document is necessary:

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

A click on a document in the tree gives access to the Definition tab where the properties and values of the document are set.

Figure: Composite document creation

Name: This is the name of the document. When first created, the Document name must be replaced. A click in the cell allows to enter a new name. The document name must follow 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).

The name of a document can start with a package prefix. For example in the Scheduler package includes the scheduler.History, scheduler.Job and scheduler.Alarm documents. A package prefix is valid when it is a Java identifier and provided it is not a Java keyword already assigned.

Properties: In the Properties tree, a click on the document item displays the list of properties which define the document. To add a property, the Add button at the bottom of the tree or the Add command from the tree context menu automatically inserts a property item in the tree. .

To add a sub-property, the property item in the upper level must be selected. The Add button at the bottom of the tree or the Add command from the tree context menu inserts another property item in the node below. A sub-property can be a composite property alike.

Selecting a property, whatever its level, updates the facing Definition sub-tab.

Figure: Composite document definition tab

For more information about configuring a property, see “Configuring a document that contains simple properties”.

When the property is properly set, another document property can be selected in the Properties list for configuration. Once the document properties are done, a click on the Apply button validates the parameters entered in the document Definition, Possible Values, and Metadata tabs.

To configure a composite document

1. In the COGNITUM Console tree, select the document you want to configure.
2. In the facing property view, unfold the document properties tree. When necessary, click Add to insert a new property.
3. In the document properties tree, select a property.
4. In the Definition sub-tab, fill in the Name box with the label you want to give to the selected property. Enter a label that follows JavaBeans naming conventions for properties. The label cannot start with a number, cannot contain dashes, spaces, and so on, and can only contain ASCII-7 characters (excluding underscores). Moreover Java/SDO keywords are prohibited.
5. In Type, select <composite>.
6. Check the following options when necessary:
   1. Mandatory to make value assignment compulsory,
   2. Monovalued to state that the matching attribute can only have one value,
   3. Read Only to make the matching attribute for view only.
   4. Unique to state that the matching attribute cannot be the same for another entry.
7. Leave the Default Values list and the Possible Values sub-tab blank.

8. Select the Metadata sub-tab when you want to specify extra data on the property:

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

10. Click the Attribute/Link cell to choose an resource attribute or link.

11. In the Properties tree, select the composite property. Click Add to insert a sub property. Configure it as described in “Configuring a document that contains simple properties”.

12. In the Properties tree, using the arrow buttons organize the properties in the order in which you want them to appear in the end-user interface.
13. Click Apply.

Additional configuration options

The following sections describe optional configuration tasks for complex documents.

Define a document primary key

If you want, you can define a primary key identifier for a document. The primary key consists of one, or more, document properties you have already created.

To define a primary key for a document

1. In the COGNITUM Console navigation pane, select the Document you want.
2. In the right pane, select a Document property you want included in the Document primary key.
3. Under the Definition tab, verify that the property’s Mandatory attribute is selected. If the Mandatory attribute is not selected, select it and click Apply. Only mandatory attributes can be part of a primary key.
4. Repeat step 3 until all properties you want included in the primary key have their Mandatory attribute selected.
5. In the right pane, select the document root node and then select the Definition tab.
6. In the right pane, under Identifier, click a blank row and using the drop-down list select a property you want included in the primary key definition.
7. Repeat step 6 until all of the properties you want included in the primary key have been added.
8. Click Apply

Define the document display fields

If you want, you can set the fields a document can display in a user interface. The display fields consists of one, or more, document properties you have already created.

To define the document display fields

1. In the COGNITUM Console navigation pane, select the Document you want.
2. In the right pane, select the Definition tab.
3. In the right pane, under Displayed Properties, click Insert.
4. Using the drop-down list select the property you want displayed.
5. Repeat step 3 and step 4 until all of the properties you want to make available for display are included.
6. Click Apply.

Define the default search criteria of a document

You can specify which document fields are searched and which document fields are included in search results.

To define the document fields that are searched

1. In the COGNITUM Console navigation panel, select the Document you want.
2. In the right panel, select the Search tab.
3. In the right pane, under Criteria, click Insert.
4. Using the drop-down list select a property you want included in the search.
5. Repeat step 3 and step 4 until all of the properties you want to include in searches are included.
6. Repeat step 3 and step 4 until all of the properties you want to make available for searches are included.
7. Click Apply.

To define the document fields that are included in search results

1. In the COGNITUM Console navigation panel, select the Document you want.
2. In the right panel, select the Search tab.
3. In the right pane, under Results, click Insert.
4. Using the drop-down list select a property you want included in search results.
5. Repeat step 3 and step 4 until all of the properties you want in search results are listed.
6. Click Apply.

Deleting a document

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

The Delete Document message box pops up. Choosing Yes validates the deletion. COGNITUM automatically updates the documents list when the document is deleted.

To delete a document

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

Improvements in Documents feature in COGNITUM 7.8.00

Basket and Bulk Operations is the new feature added in COGNITUM 7.8. This feature is similar to the normal search. The difference is that you can select multiple entries to add in basket and perform some bulk operations like sending emails, update, export & delete.

Basket and Bulk Operationsis explained in the document Application with new Features and Improvements in COGNITUM 7.8.