Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Preparing Lotus Notes : Managing Lotus Notes Documents

Managing Lotus Notes Documents
In addition to the general documents that are used to hold the data, a TIBCO-enabled Lotus Notes Database provides administration documents to facilitate the data manipulation. This section describes how to work with the Lotus Notes Administration documents.
Lotus Notes Administration Documents
Every TIBCO-enabled Lotus Notes database that you create must include all the Lotus Notes administration documents.
Documents for TIBCO-enabled Lotus Notes databases are created based on the forms inherited from the TIBCO-enabled database template. The TIBCO-enabled database template also includes one instance of each document. The sample documents contain default data that is needed to set up and test a TIBCO-enabled database. Documents that are created based on the forms do not contain default data. Ensure that every new TIBCO-enabled database copies these documents from the templates.
The databases may contain other forms and you can also customize the standard TIBCO forms, but they must include the fields from the original forms.
Each document consists of a set of fields. For many of the fields, a corresponding repository object is listed. If changes are made to the field values, the corresponding repository object values must be modified. Additionally, the field values must be set to the same value as the corresponding repository object.
Setup Document
The Setup document is used by the publishing mechanism of the Publication Service and Request-Response Invocation Service. The Lotus Notes agents use the Setup document to establish a TIBCO Rendezvous or JMS session.
Creating a Setup Document
To create a Setup document:
1.
2.
From the Create menu, select TIB Adapter Setup Form.
3.
Figure 11 Setup Document
4.
Table 4 lists the fields in the setup document.
 
The name of the.nsf file where the agent logs should be created.
The .nsf file specified should have the Log Entry form and the Agent Activity View of the StdR4AgentLog template (ALOG4.NTF) copied into it. User can select either or both options to maintain the log files.
Applies to Publication Service and Request-Response Invocation Service for which triggers are configured and when HTTP are used as the transport type.
The value of this field must be the same as that of the Http Port to Listen to LotusNotes Events field in the Adapter Services tab of an adapter instance.
Applies to Publication Service and Request-Response Invocation Service for which triggers are configured and when Rendezvous is used as the transport type.
The value of this field should be the same as that of the Subject to Listen to LotusNotes Events field in the Adapter Services tab of an adapter instance.
The default value is 2000. The maximum allowed value is 5000. If the value is set to -1, the documents wouldn’t be processed in batch.
The batch file name. The RV agent calls the batch file which is used to run SendRvPub.class. The name can be specified for use by different databases. Specify the full path name for this field.
The batch file name. The RV agent calls the batch file which is used to run SendRvMsgInitClient.class. The name can be specified for use by different databases.
Maintaining the Setup Document
Once created, the Setup document appears in TIB Administration\1. Setup View. You can double-click the document to modify it at a later time.
Event Setup Document
Event Setup document is only used by the Publication Service. An Event Setup document defines the conditions that a document must meet in order to be processed, and how the document is copied to the Publishing Status view.
Because they are started for publishing transactions, the Lotus Notes agents read data from the document. The document must match the formula defined in an event setup document before the publishing transaction can be initiated.
One form can be attached to multiple events, however each event must have a unique event name to ensure that there is no ambiguity about which event is to be applied.
Creating an Event Setup Document
To create an event setup document:
1.
2.
From the Create menu, select TIB Publisher Event Form.
3.
Figure 12 Event Setup Document
Specify values for the fields of Event Name, Host Name, Port Number, Override Subject, and Formula. Leave the other fields unchanged.
4.
Table 5 lists the fields in the event setup document.
 
For the Publication Service, ensure that the Event Name matches the part after the dot. For example, if the value of the Class Reference field under the Schema tab in TIBCO Designer is /AESchemas/ae/lotusnotes/lnmetadata.aeschema#class.customer, then the Event Name should be customer.
The combination of Host Name and Port Number for an event setup document must be unique in its database.
The combination of Host Name and Port Number for an event setup document must be unique in its database.
Notify the adapter configuration of the published data. This is only used when the publish over-ride agent is started, rather than taking the subject from the XML file. It has higher priority than the override subject in the Setup Document.
Maintaining the Event Setup Document
Once created, the event setup document appears in TIB Administration\2. Events View. You can double-click the document to modify it at a later time.
Client Requests Document
The Client Requests document is used only for the Request-Response Invocation Service. The Request-Response Invocation View form in the sample.nsf file is a client-request-enabled form.
The TIB InitiateClientRequest agent is run against a client-request-enabled document. When the agent is invoked against one of these documents, it creates a Client Request Processing Document which is used by the adapter to process the client request. This kind of document is only used by the TIB InitiateClientRequest agent.
Creating a Client Requests Document
To create a client requests document:
1.
2.
From the Create menu, select TIB Client Request Form.
3.
Set the values according to your application requirements. You can configure different RV parameters for different events which serve different services in the adapter.
Figure 13 Client Requests Document
4.
Table 6 lists the fields of the Defined Client Requests Document.
The name of the meta data class that is associated with the request. This class must be defined in the Class Reference field in the Schema tab of the adapter service.
Used by the RV agent to identify the subject for Rendezvous transport. Override Subject has higher priority than Publish Subject in the Setup View.
The RV agent first looks at the documents in the Defined Client Request View. If the RV parameter is configured, then the agent simply uses them. Otherwise, use the RV parameter configured in the document of the Setup view.
The name of the SDK client that is to be used internally by this client request. This client object must be defined in the Configuration Data associated with the adapter.
The format of a Client Name is the Request Name of the same document appended with the string Endpoint. For example, if the Request Name is RPCC, then the Client Name should be RPCCEndpoint.
The value in milliseconds for which the synchronous client request will wait for the response of the request. If this response does not come within this time limit, the entire operation will time out.
Parameters that are defined in the metadata object. The values are given to this field as part of the operation definition. The logic is such that the value field must have valid parameters of the document fields associated with the parameters of the operation object containing the operation.
For example, parm1 and requestedField are attributes of RequestReplyOperations in the LOTUS_NOTES_RPC class. Use TIBCO Designer to access it in the following location: AESchemas/ae/lotusnotes/replymetadata/Classes.
If one of the document fields is not really part of the document or is part of the document but does not contain a value, then the value ^NO_VALUE^ will be given to the parameter and it will not be used in initiating the internal request.
This field is related to the OperationParameters field.
For example, the RequestedFields attribute of the Request-Response Invocation View form has been mapped to requestedField of RequestReplyOperations in the LOTUS_NOTES_RPC class. Use TIBCO Designer to access it in the following location: AESchemas/ae/lotusnotes/replymetadata/Classes.
Maintaining the Client Requests Document
Once created, the client requests document appears in TIB Administration\5. Defined Client Requests. You can double-click the document to modify it at a later time.
Request Response Invocation Document
The Request Response Invocation document is used to initiate a client request for Request-Response Invocation Service.
Creating a Request Response Invocation Document
To create a Request Response Invocation document:
1.
2.
From the Create menu, select Request Response Invocation Form.
3.
Set the values according to your application requirements. You can configure different RV parameters for different events which serve different services in the adapter.
Figure 14 Request Response Invocation Document
Table 7 lists the fields of the Request Response Invocation document.
The type of query operation. Valid values can be Query, View, FTSearch, and RunAgent. When communicating with a Request-Response Service whose operation type is query, specify detailed query information with this option.
Query by formula. If the value of the Operation Type field is set to query, a Lotus formula needs to be specified in this field. See Guidelines for Using Formula.
Invokes a predefined agent to perform the query. If the value of the Operation Type field is set to RunAgent, an agent name has to be specified in this field.
The agent specified here must have a Target setting other than All selected documents when created in Lotus Domino Designer.
Query by view. If the value of the Operation Type is set to View, a view name needs to be specified in this field. With this option, all documents in the specified view will be returned.
Indicates the status of the request. Valid statuses include Unprocessed, Processed, Exception, and Timed Out. When a document is first created, the status is set to Unprocessed.
The return value of the RPC operation. The structure of the return value is defined in the meta-class definition that is associated with this client request.
The return data of the RPC operation. The structure of the return data is defined in the meta-class definition that is associated with this client request.
The exception name of the RPC operation, if any. The structure of the exception is defined in the meta-class definition that is associated with this client request.
The return value of the RPC operation. The structure of the exception is defined in the meta-class definition that is associated with this client request.
Guidelines for Using Formula
TIBCO ActiveMatrix Adapter Service Engine for Lotus Notes supports the formula language.
For example,
to search for documents in the form named test, enter Form="test" in the Formula field.
to search for documents in the form named customer and have the key field customertype set to type3, enter Form="customer"&customertype="type3" in the Formula Field.
For more information about how to use the formula language, refer to the Lotus Domino Designer documentation.
Guidelines for Setting FTSearch Parameters
When setting the FTSearch parameters, follow the method syntax described below:
where queryStr is a string that defines the full-text query
The character \ is defined as the escape mark.
The characters * and ? are defined as the wildcards.
To search strings that include the characters {, }, (, ), &, [, ], |, !, :, ', ;, <, or >, enclose the query string in double-quotes.
To search strings that include the characters *, ?, or double-quotes, use | as the escape mark in the query string.
To search strings that include commas or slashes, use \ as the escape mark in the query string.
For example,
to search for fields that contain a plain string TIBexampleTIB, enter TIBexampleTIB in the Parameters field.
to search for fields that contain string {}TIB(example&TIB[], enter "{}TIB(example&TIB[]" in the Parameters Field.
to search for fields that contain string TIB"exa*ple?TIB, enter TIB|"exa|*ple|?TIB in the Parameters Field.
to search for fields that contain string TIB,example\TIB, enter TIB\,example\\TIB in the Parameters Field.
where:
queryStr is a string that defines the full-text query
max is an integer that indicates the maximum number of documents to be returned from the query. Set max to 0 to receive all matching documents.
For example, to returned the first five documents which contain string TIBexampleTIB, enter TIBexampleTIB,5 in the Parameters Field.
queryStr, max, sortopt, otheropt
where:
queryStr is a string that defines the full-text query
max is an integer that specifies the maximum number of documents to be returned from the query. Set max to 0 to receive all matching documents.
sortopt is an integer that specifies a sorting option. Refer to the Lotus Domino Designer documentation for details about this option.
otheropt is an integer that specifies additional search options. Refer to the Lotus Domino Designer documentation for details about this option.
For example, to use fuzzy search (FT_FUZZY) to return the first five documents that contain string TIBexampleTIB and the returned documents are sorted by creation date in descending order (FT_DATECREATED_DES), enter TIBexampleTIB,5,1542, 16384 in the Parameters Field.
Maintaining the Request Response Invocation Document
Once created, the Request Response Invocation document appears in the Request Response Invocation View. You can double-click the document to modify it at a later time.
Customizing Views for the Request Response Invocation Documents
You can define different views to manipulate the Request Response Invocation Documents.
For example, create views for each operation type.
1.
2.
3.
4.
In the Select Conditions text box, type SELECT Form="Request Response Invocation Form" & operationType="1". This selection condition ensures that the view connects to the Request Response Invocation Form. Leave other fields unchanged.
5.
6.
Repeat the steps above to create views for other operation types. Change the value of the operationType in the Select Conditions text box accordingly.
Client Requests Processing View
This view lists the requests that are currently in process and are being processed by the adapter client configuration or that have already been processed by the adapter client configuration.
Documents listed in this view are created by the TIB InitiateClientRequest agent, which is used in conjunction with the adapter configuration to process the client request that has been initiated by the user agent.
Once the client request has been processed by the adapter configuration, the status field and response-related fields of the document are manipulated. The form for this view should contain the fields in the Defined Client Requests document in addition to the fields defined in Table 8.
When the adapter configuration completes the client request, the values of the status field and the response field change accordingly.
Figure 15 Client Requests Processing Document
 
Publishing Status View
The Publishing Status view lists all publishing transactions. It indicates the document ID which is to be published and the publishing status of the document.
The status flags available are as follows:
UnPublished —Indicates that the document has been moved to the outbox by the Publisher agent and has not yet been taken for publishing by the adapter.
Double-click an event to see more information about the document.
 
If the publisher has been down for a substantial amount of time and an agent is still running, the Lotus Notes documents will be queued in the Publishing Status document of the database. Ensure that the documents are published before the count goes beyond 10,000. To do this, you can either use a TIBCO Hawk rule base to restart the adapter or restart the adapter manually.
Unpublished View
The Unpublished View lists all the publication requests that have not yet been executed.
 

Copyright © TIBCO Software Inc. All Rights Reserved