TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB User s Guide

Transcription

1 TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB User s Guide Software Release 1.0 December 2014 Two-Second Advantage

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO Hawk, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright 2014 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 iii Contents Figures vii Tables ix Preface xi Related Documentation xii TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB Documentation xii Other TIBCO Product Documentation xii Third-Party Documentation xii Typographical Conventions xiii Connecting with TIBCO Resources xv How to Join TIBCOmmunity xv How to Access TIBCO Documentation xv How to Contact TIBCO Support xv Chapter 1 Product Introduction MongoDB Overview Plug-in Overview Chapter 2 Getting Started Overview Creating a Project Configuring a MongoDB Connection Creating a Process Adding Activities to a Process Testing a Process Deploying a Project Chapter 3 MongoDB Palette Palette Overview MongoDB Connection Configuration Security

4 iv Contents Insert Document Configuration Input Output Error Output Query Documents Configuration Input Output Error Output Fetching Subsets of the Result Set Update Document Configuration Input Output Error Output Remove Document Configuration Input Output Error Output Get MongoDB Connection Configuration Input Output Error Output Database Command Configuration Input Output Error Output Map-Reduce Configuration Input Output Error Output Chapter 4 Working with Sample Projects Overview of Sample Projects Hierarchical-Aggregation Project MapReduceAggregate Process QueryAggregate Process

5 Contents v QueryDocuments Process Metadata_and_Asset_Management Project RESTDelete Process RESTServices Process Query JSON to XML Process Save XML to MongoDB Process GridFS Photo Operate Process Query by Index Process Appendix A Managing MongoDB Logs Managing Logs Appendix B Error Codes Error Codes Index

6 vi Contents

7 Figures vii Figures Figure 1 Cooperation Between the Plug-in and TIBCO Products Figure 2 TIBCO Designer Dialog Figure 3 TIBCO Designer Save Project Dialog Figure 4 MongoDB Palette Figure 5 MapReduceAggregate Process Figure 6 QueryAggregate Process Figure 7 QueryDocuments Process Figure 8 Clean Insert Documents Subprocess Figure 9 Insert Document Subprocess Figure 10 RESTDelete Process Figure 11 RESTServices Process Figure 12 Query JSON to XML Process Figure 13 Save XML to MongoDB Process Figure 14 GridFS Photo Operate Process Figure 15 Query by Index Process Figure 16 Create Documents Subprocess Figure 17 Create GridFS File Subprocess Figure 18 Delete Document Subprocess Figure 19 Delete Photo Subprocess Figure 20 Query Document Subprocess Figure 21 Query GridFS Photos Subprocess Figure 22 Query Many Documents Subprocess Figure 23 Drop Index Subprocess Figure 24 Update Document Subprocess

8 viii Figures

9 Tables ix Tables Table 1 General Typographical Conventions xiii Table 2 MongoDB Connection Configuration Table 3 MongoDB Connection Security Table 4 MongoDB Insert Document Configuration Table 5 MongoDB Insert Document Input Table 6 MongoDB Insert Document Output Table 7 MongoDB Insert Document Exceptions Table 8 MongoDB Query Documents Configuration Table 9 MongoDB Query Documents Input Table 10 MongoDB Query Documents Output Table 11 MongoDB Query Documents Exceptions Table 12 Example of Fetching Subsets of the Result Set Table 13 MongoDB Update Document Configuration Table 14 MongoDB Update Document Input Table 15 MongoDB Update Document Output Table 16 MongoDB Update Document Exceptions Table 17 MongoDB Remove Document Configuration Table 18 MongoDB Remove Document Input Table 19 MongoDB Remove Document Output Table 20 MongoDB Remove Document Exceptions Table 21 MongoDB Get MongoDB Connection Configuration Table 22 MongoDB Get MongoDB Connection Output Table 23 MongoDB Get MongoDB Connection Exceptions Table 24 MongoDB Database Command Configuration Table 25 MongoDB Database Command Input Table 26 MongoDB Database Command Output Table 27 MongoDB Database Command Exceptions Table 28 MongoDB Map-Reduce Configuration

10 x Tables Table 29 MongoDB Map-Reduce Input Table 30 MongoDB Map-Reduce Output Table 31 MongoDB Map-Reduce Exceptions Table 32 MapReduceAggregate Process Activities Table 33 QueryAggregate Process Activities Table 34 QueryDocuments Process Activities Table 35 Clean Insert Documents Subprocess Activities Table 36 Insert Document Subprocess Activities Table 37 RESTDelete Process Activities Table 38 RESTServices Process Activities Table 39 Query JSON to XML Process Activities Table 40 Save XML to MongoDB Process Activities Table 41 GridFS Photo Operate Process Activities Table 42 Query by Index Process Activities Table 43 Create Documents Subprocess Activities Table 44 Create GridFS File Subprocess Activities Table 45 Delete Document Subprocess Activities Table 46 Delete Photo Subprocess Activities Table 47 Query Document Subprocess Activities Table 48 Query GridFS Photos Subprocess Activities Table 49 Query Many Documents Subprocess Activities Table 50 Drop Index Subprocess Activities Table 51 Update Document Subprocess Activities Table 52 Log Properties Table 53 Error Codes

11 xi Preface TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB, integrated with TIBCO ActiveMatrix BusinessWorks, provides you with a user-friendly way to make use of MongoDB. This manual is not intended to be a complete reference for developing process definitions using TIBCO ActiveMatrix BusinessWorks. Having a good knowledge of TIBCO ActiveMatrix BusinessWorks and MongoDB is a prerequisite for using this plug-in. Topics Related Documentation, page xii Typographical Conventions, page xiii Connecting with TIBCO Resources, page xv

12 xii Related Documentation Related Documentation This section lists documentation resources you may find useful when using TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB. TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB Documentation The following documents form the TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB documentation set: TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB Installation Read this manual for instructions on site preparation and installation. Read this manual for instructions on using the product. TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release. Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: TIBCO ActiveMatrix BusinessWorks TIBCO Administrator TIBCO Designer TIBCO Hawk TIBCO Rendezvous TIBCO Runtime Agent Third-Party Documentation You may also find it useful to read the MongoDB product documentation available on

13 Preface xiii Typographical Conventions This manual uses the following typographical conventions. Table 1 General Typographical Conventions Convention ENV_NAME TIBCO_HOME Use TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties: Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer. The name is also a component of the path to the product shortcut in the Windows Start > All Programs menu. Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME. TIB_bwpluginm ongodb_home code font TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB is installed into a directory within TIBCO_HOME. This directory is referenced in documentation as TIB_bwpluginmongodb_HOME. The default value of TIB_bwpluginmongodb_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\bw\plugins\mongodb. Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process. bold code font Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable disable]

14 xiv Typographical Conventions Table 1 General Typographical Conventions (Cont d) Convention italic font Key combinations Use Italic font is used in the following ways: To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts. To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q. The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

15 Preface xv Connecting with TIBCO Resources How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to How to Access TIBCO Documentation You can access TIBCO documentation here: How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows: For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a user name and password. If you do not have a user name, you can request one.

16 xvi Connecting with TIBCO Resources

17 1 Chapter 1 Product Introduction This chapter gives an overview of MongoDB and TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB. Topics MongoDB Overview, page 2 Plug-in Overview, page 3

18 2 Chapter 1 Product Introduction MongoDB Overview MongoDB is an open-source, document-oriented database designed for ease of development and scaling. A record in MongoDB is a document, which is a data structure composed of field and value pairs. MongoDB documents are BSON documents. BSON is a binary representation of JSON with additional type information. In a MongoDB document, the value of a field can be any of the BSON data types, including other documents, arrays, and arrays of documents. If you are not familiar with MongoDB, you can refer to the MongoDB product documentation available on for more information.

19 Plug-in Overview 3 Plug-in Overview TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB provides you with a user-friendly environment to manage documents and files in MongoDB. The plug-in contains the MongoDB Palette, which includes the MongoDB Connection shared resource and following activities: Insert Document Query Documents Update Document Remove Document Get MongoDB Connection Database Command Map-Reduce Figure 1 shows how the plug-in works with TIBCO products. Figure 1 Cooperation Between the Plug-in and TIBCO Products MongoDB MongoDB Plug-in TIBCO ActiveMatrix BusinessWorks TIBCO Designer TIBCO Administrator MongoDB is an open-source, document-oriented database that provides high performance, high availability, and automatic scaling. For more information about MongoDB features and functionalities, visit MongoDB website at TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB plugs into TIBCO ActiveMatrix BusinessWorks and connects TIBCO ActiveMatrix BusinessWorks and MongoDB. TIBCO ActiveMatrix BusinessWorks is an easy-to-use integration product suite for enterprise applications.

20 4 Chapter 1 Product Introduction TIBCO Designer is the graphical user interface (GUI) used by TIBCO ActiveMatrix BusinessWorks and the plug-in to design business processes and the process engine to execute them. TIBCO Administrator provides a centralized administrative interface to manage and monitor the plug-in applications deployed in an enterprise.

21 5 Chapter 2 Getting Started This chapter describes the basic steps that are required to configure and run TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB in TIBCO Designer. Topics Overview, page 6 Creating a Project, page 7 Configuring a MongoDB Connection, page 9 Creating a Process, page 10 Adding Activities to a Process, page 11 Testing a Process, page 12 Deploying a Project, page 13

22 6 Chapter 2 Getting Started Overview TIBCO ActiveMatrix BusinessWorks is an easy-to-use integration product suite designed for enterprise applications. It uses TIBCO Designer GUI for defining business processes and uses the process engine to execute defined processes. For detailed information about how to configure processes, see TIBCO Designer documentation, which can be accessed on Help > Designer Help in TIBCO Designer. A typical configuration session contains the following steps: 1. Creating a Project, page 7 2. Configuring a MongoDB Connection, page 9 3. Creating a Process, page Adding Activities to a Process, page Testing a Process, page Deploying a Project, page 13

23 Creating a Project 7 Creating a Project The TIBCO Designer GUI is used to build a project. When starting TIBCO designer, you must create or select a project. A project contains the configuration files that define options used during runtime. To create a project, complete the following steps: 1. Start TIBCO Designer. Execute one of the following platform-specific operations to open the TIBCO Designer window: On Microsoft Windows Click Start > All Programs > TIBCO > TIBCO Designer version_number> TIBCO Designer. Or From a command window, run TIBCO_HOME\designer\version_number\bin\designer.exe. On Linux From a command window, run TIBCO_HOME/designer/version_number/bin/designer. 2. Click New empty project in the TIBCO Designer dialog, as shown in Figure 2. Figure 2 TIBCO Designer Dialog

24 8 Chapter 2 Getting Started 3. In the Save Project dialog, click Select a file from the file system in the Multi-File Project tab to navigate to the location where you intend to save the project or directly type the path in the Project Directory field. Click OK to save the project, as shown in Figure 3. Figure 3 TIBCO Designer Save Project Dialog

25 Configuring a MongoDB Connection 9 Configuring a MongoDB Connection After creating a TIBCO Designer project, you require to add a MongoDB Connection shared resource and configure it. The MongoDB Connection shared resource is used for all MongoDB activities. It contains all necessary parameters to establish a connection between the plug-in and the MongoDB database. To create a MongoDB Connection shared resource, complete the following steps: 1. In the Project panel, expand the project folder created in Creating a Project on page Click the MongoDB palette in the Palettes tab, and drag the MongoDB Connection to the Design panel on the right. 3. Configure the created MongoDB Connection shared resource. See MongoDB Connection on page 17 for more information. 4. Click Apply to save the configuration.

26 10 Chapter 2 Getting Started Creating a Process After creating a project and configuring the MongoDB Connection shared resource, create a process to deal with certain workflows. To create a process, complete the following steps: 1. Click a project you created in the Project panel. 2. Add a process using either of the following ways: Expand the Process palette in the Palettes tab and drag the Process Definition into the Design panel. Or Right-click the created project and click Add Resource > Process > Process Definition from the pop-up menu. 3. Configure the process. Refer to TIBCO Designer User s Guide for more information about how to configure a process. 4. Click Apply to save the configuration.

27 Adding Activities to a Process 11 Adding Activities to a Process After creating a process, you can add plug-in activities to the process. To add an activity to the process, complete the following steps: 1. Click the process which was created in Creating a Process on page 10. The Start and End activities are displayed in the Design panel. 2. Expand the MongoDB palette in the Palettes tab and drag one or more activities to the Design panel. You can add activities from other palettes to the process, for example, File activities. If the MongoDB palette is not shown in the Palettes tab, click Palettes > Activities > MongoDB to make it visible. 3. Click Create transition on the TIBCO Designer toolbar to draw transitions between activities in the Design panel. 4. Configure each activity in the process. For detailed information, see MongoDB Palette on page 15.

28 12 Chapter 2 Getting Started Testing a Process After creating and configuring a process, test it in TIBCO Designer. This allows you to check if the process works properly before you deploy it. For detailed information about using the Test mode, see TIBCO ActiveMatrix BusinessWorks Process Design, Chapter 18, "Testing Process Definitions."

29 Deploying a Project 13 Deploying a Project To deploy a project you configured, you require to generate an Enterprise Archive (EAR) file that contains configuration for the process definition you want to deploy. You can upload the archive to TIBCO Administrator to deploy the associated application. See TIBCO ActiveMatrix BusinessWorks Administration for more information. To deploy a project, complete the following steps: 1. Save the project in the TIBCO Designer window. Make sure the processes saved in the project can be triggered. 2. Click Tools > Create Project EAR to create an EAR file. 3. Select the Process Archive resource in the created EAR. In the Processes tab, click to specify the process definitions to include. Click Apply to save the configuration. 4. Click Build Archive in the Enterprise Archive panel. An Enterprise Archive file is generated by TIBCO Designer and then you can deploy it by using TIBCO Administrator. 5. Start TIBCO Administrator and create an application related to the project. 6. Upload the generated EAR file. 7. Deploy the application and start the process. You can define multiple EAR resources for a single Designer project. For each archive, you can choose the processes to include. See TIBCO ActiveMatrix BusinessWorks Administration for more details on how to deploy an application.

30 14 Chapter 2 Getting Started

31 15 Chapter 3 MongoDB Palette This chapter describes the TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB palette, which includes a shared resource and 7 activities. Topics Palette Overview, page 16 MongoDB Connection, page 17 Insert Document, page 21 Query Documents, page 28 Update Document, page 38 Remove Document, page 44 Get MongoDB Connection, page 50 Database Command, page 53 Map-Reduce, page 57

32 16 Chapter 3 MongoDB Palette Palette Overview The MongoDB palette includes a shared resource and 7 activities, as show in Figure 4. Figure 4 MongoDB Palette Shared resource: MongoDB Connection Activities: Insert Document Query Documents Update Document Remove Document Get MongoDB Connection Database Command Map-Reduce

33 MongoDB Connection 17 MongoDB Connection Shared Resource The MongoDB Connection shared resource contains all necessary parameters to establish a connection to a MongoDB database. The MongoDB Connection shared resource must be specified when running any MongoDB activity. Configuration The Configuration tab contains the following fields. Table 2 MongoDB Connection Configuration (Sheet 1 of 3) Field Global Variab le? Name No (Required) Name of the shared resource. The default value is MongoDB Connection. No (Optional) A short description of the shared resource. Click and add the description in the dialog. The following fields are displayed when the Plain URL check box is cleared. Host&Port Yes (Required) Specifies the server address and the port number. You can specify multiple hosts if you want to connect to replica sets. The following is the standard format of the string: host1[:port1][, host2[:port2],...[, hostn[:portn]]] where: host1 is the only required part of the URL which identifies a server address. It can be a hostname, IP address, or UNIX domain socket. :port1 is an optional parameter which specifies a port number. If it is unspecified, :27017 is used by default. hostx is an optional parameter which identifies another server address. :portx is an optional parameter which specifies a port number. If it is unspecified, :27017 is used by default. For example: localhost, localhost:27018, localhost:27019 The default value is localhost:27017

34 18 Chapter 3 MongoDB Palette Table 2 MongoDB Connection Configuration (Sheet 2 of 3) Field Database Name ConnectTime out(millisecon ds) SocketTimeou t(milliseconds ) MaxWaitTime (milliseconds) Global Variab le? Yes Yes Yes Yes (Required) Name of a target database. The default name is databasename. (Required) The maximum amount of time that a MongoDB driver waits for a connection to be established with a MongoDB server. The default value is milliseconds. (Required) The maximum amount of time that a socket waits for a send or receive before timing out. The default value is 0 milliseconds. (Required) The maximum amount of time that a thread waits for a socket from the connection pool. The default value is milliseconds. MaxPoolSize Yes (Required) The maximum number of connections in the connection pool. The default value is 100.

35 MongoDB Connection 19 Table 2 MongoDB Connection Configuration (Sheet 3 of 3) Field Global Variab le? The following fields are displayed when the Plain URL check box is selected. Connection URL Database Name Yes Yes (Required) The URL of the MongoDB server that you want to connect to. The following is the standard format of the MongoDB connection URL: mongodb://host1[:port1][, host2[:port2],...[, hostn[:portn]]]/[?opts] where: mongodb:// is a required prefix to indicate this connection string is used to connect to MongoDB. host1 is a required part of the URL which identifies the server address. It can be a hostname, IP address, or UNIX domain socket. :port1 is an optional parameter which specifies a port number. If it is unspecified, :27017 is used by default. hostx is an optional parameter. You can specify multiple hosts when connecting to replica sets. :portx is an optional parameter which specifies a port number. If it is unspecified, :27017 is used by default.?opts are optional parameters which specify other connection string options, including the replica set option, connection options, connection pool options, write concern options, read preference options, authentication options, miscellaneous configuration, and so on. For more instructions on how to specify these options in a connection URL, refer to For example: mongodb://localhost, localhost:27018, localhost: 27019/?replicaSet=test The default value is mongodb://localhost:27017/?connecttimeoutms=10000&socketti meoutms=0&waitqueuetimeoutms=120000&maxpoolsize=100 (Required) Name of a target database. The default name is databasename.

36 20 Chapter 3 MongoDB Palette Security The Security tab contains the following fields. Table 3 MongoDB Connection Security Field Global Variable? CR Credential Authentication The UserName, and Password fields are displayed after you select the CR Credential check box. CR Credential Yes Specifies whether or not you want to authenticate the user name and password when connecting to a MongoDB database. UserName Yes Required when the CR Credential check box is selected. The user name you created in a MongoDB database. Password Yes Required when the CR Credential check box is selected. The password of the user name specified in the UserName field. Kerberos Authentication The Kerberos UserName field is displayed after you select the Kerberos check box. Kerberos Yes Specifies whether or not you want to use the Kerberos authentication to authenticate against a MongoDB cluster. Note: Kerberos authentication is only supported on Linux operating system in this release. Kerberos UserName Yes Required when the Kerberos check box is selected. The Kerberos user name. It depends on the Kerberos server configuration. Note: With Kerberos you neither specify the password nor the database name. Note: TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB does not support SSL authentication in this release. After configuring the MongoDB Connection, click Test Connection to test whether the specified configuration fields result in a valid connection to the MongoDB database.

37 Insert Document 21 Insert Document Activity The Insert Document activity supports the following functionalities: Inserts a single document into a collection. Inserts a single file into a bucket. Batch operations. You can insert a group of documents into a collection or insert multiple files into a bucket at each time. Configuration The Configuration tab contains the following fields. Table 4 MongoDB Insert Document Configuration (Sheet 1 of 3) Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Insert Document. No (Optional) A brief description of the activity. Click and add the description in the dialog. MongoDB Connection Collection Name Yes Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity. (Required) Name of the collection into which you want to insert a new document or a group of documents. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted.

38 22 Chapter 3 MongoDB Palette Table 4 MongoDB Insert Document Configuration (Sheet 2 of 3) Field Write Concern Global Variable? Yes (Required) Specifies an assurance that MongoDB provides when reporting on the success of a write operation. Note: The strength of a write concern determines the level of an assurance. When performing a write operation which has a weak write concern, the write operation returns quickly. While performing a write operation with a strong write concern, the client will wait for the MongoDB to confirm the write operation before reporting the result the operation. MongoDB provides the following levels of write concern, listed from the weakest to strongest: UNACKNOWLEDGED: With an unacknowledged write concern, MongoDB does not acknowledge the receipt of a write operation and the write operation returns as soon as the message is written to the socket. Only network errors are captured and handled. ACKNOWLEDGED: With a receipt acknowledged write concern, a write operation waits for an acknowledgement from the primary server before returning a result. Network, duplicate key, and other errors are captured and handled. JOURNALED: With a journaled write concern, MongoDB acknowledges a write operation after committing the data to the journal. Both network issues and server errors are captured and handled. This type of write concern ensures that MongoDB can recover the data if there is a shutdown or power interruption emergency. Before using this type of write concern, you must have journaling enabled. FSYNCED: With a fsynced write concern, a write operation waits for the server to flush data to the disk before returning a result. Network, duplicate key, and other errors are captured and handled. REPLICA_ACKNOWLEDGED: With a replica acknowledged write concern, a write operation waits for acknowledgements from at least 2 servers before returning a result. Network, duplicate key, and other errors are captured and handled. MAJORITY: With a majority write concern, a write operation waits for acknowledgements from a majority of servers before returning a result. Network, duplicate key, and other errors are captured and handled.

39 Insert Document 23 Table 4 MongoDB Insert Document Configuration (Sheet 3 of 3) Field Continue On Error Global Variable? Yes (Optional) A parameter which controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. When the check box is selected, MongoDB continues to process the remaining write operations if an error occurs when processing one of the write operations. Is GridFS Yes (Optional) GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB. Select this check box if you want to insert one or more files into a bucket. Input The Input tab contains the following fields. Table 5 MongoDB Insert Document Input (Sheet 1 of 3) Field Data Type CollectionName String (Optional) Name of the collection into which you want to insert a document or a group of documents. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. The value specified in this field takes precedence over the value given in the Collection Name field of the Configuration tab. Document JSONString (Required) The document which you want to insert into the specified collection. Note: You can insert a group of documents into a collection at each time.

40 24 Chapter 3 MongoDB Palette Table 5 MongoDB Insert Document Input (Sheet 2 of 3) Field Data Type ContinueOnError Boolean (Optional) A parameter which controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. A valid value of this field is 1 (true) or 0 (false). The default value is 0 (false). Index The value specified in this field takes precedence over the value given in the Continue On Error field of the Configuration tab. IndexDocument JSONString (Optional) A document used to create a new index on a specific field. Note: You can create an index on any field or embedded field within a document or sub-document. For more instructions on creating an index, refer to eation/. IndexOptionsDoc ument JSONString (Optional) A document which contains a set of options and is used to set index properties when building an index. For more information about index properties you can specify when building an index, refer to The following fields are displayed when the Is GridFS check box is selected in the Configuration tab. BucketName String (Optional) Name of the bucket into which you want to insert one or more files. The default bucket name is fs. Note: A valid bucket name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted.

41 Insert Document 25 Table 5 MongoDB Insert Document Input (Sheet 3 of 3) Field Data Type GridFSFile FullFileName String (Required) The full path name of the file which you want to add into a bucket. Note: You can insert multiple files into a bucket at each time. NewFileName String (Optional) You can specify a new file name for a file when adding it into a bucket. Output The Output tab contains the following fields. Table 6 MongoDB Insert Document Output Field Data Type ResultDocument JSONString A document which records the status of the Insert Document activity. TotalCount Integer The total count of documents which you expected to insert into the specified collection. SucceedNum Integer The total count of documents which you successfully inserted into the specified collection. FailedNum Integer The total count of documents which you failed to insert into the specified collection. Error Output The Error Output tab contains the following fields. Table 7 MongoDB Insert Document Exceptions Error Schema Element MongoDBPluginException Data Type msg String This error message is displayed when the MongoDB plug-in captures an exception for the Insert Document activity.

42 26 Chapter 3 MongoDB Palette Table 7 MongoDB Insert Document Exceptions (Cont d) Error Schema Element msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Insert Document activity. MongoException msg String This error message is displayed when the MongoDB encounters internal errors. msgcode String This error code is displayed when the MongoDB encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code when a network-related exception occurs. JSONParseException msg String This error message is displayed when an invalid JSON object is passed to the JSON parser. msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser. DuplicateKeyException Data Type msg String This error message is displayed when an error of duplicate key occurs. msgcode String This error message is displayed when an error of duplicate key occurs.

43 Query Documents 27 Query Documents Activity The Query Documents activity supports the following functionalities: Queries a single or all documents from a collection. Queries all documents containing a certain field with a specified value from a collection using equality condition or query operators. Counts the total number of documents matching a query condition in a collection. Queries distinct values of a certain field from a collection. Executes an aggregation on a collection with an aggregation pipeline or a map-reduce operation. Queries a single or multiple files matching a query condition from a bucket. You can also use the Query Documents activity to limit the fields returned in matching documents and the maximum number of documents displayed in the output result for each query operation, as well as define the display order of the documents in the output result. Configuration The Configuration tab contains the following fields. Table 8 MongoDB Query Documents Configuration (Sheet 1 of 3) Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Query Documents. No (Optional) A brief description of the activity. Click and add the description in the dialog. MongoDB Connection Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity.

44 28 Chapter 3 MongoDB Palette Table 8 MongoDB Query Documents Configuration (Sheet 2 of 3) Field Collection Name Global Variable? Yes (Required) Name of the collection on which you want to execute a query operation. Notes: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. Query Type Yes (Required) Specifies the query type you intend to execute. Select one from the following options: FIND_ONE: Finds the first document matching a query condition. FIND_MANY: Finds all documents matching a query condition. COUNT: Counts the total number of documents matching a query condition. DISTINCT: Finds an array of distinct values for a specified field. AGGREGATE: Processes documents in a collection by using a versatile staged-based data processing pipeline or map-reduce operations.

45 Query Documents 29 Table 8 MongoDB Query Documents Configuration (Sheet 3 of 3) Field Read Preference Global Variable? Yes (Required) Determines how the client directs read operations to the members of a replica set. Select one option from the following list: PRIMARY: The default mode. Operations read from the primary member of a replica set. PRIMARY_PREFERRED: Operations read from the primary member preferentially, but if the primary member is unavailable, operations read from secondary members of a replica set. SECONDARY: Operations read from secondary members of a replica set. SECONDARY_PREFERRED: Operations read from secondary members preferentially, but if no secondary members are available, operations read from the primary member of a replica set. NEAREST: Operations read from a member of a replica set with the least network latency, irrespective of the member type of the replica set. Note: The read preference functionality does not support for the aggregate query type, so when you select AGGREGATE from the Query Type list, the Read Preference list is disabled. Is GridFS Yes (Optional) GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB. Select this check box if you want to query one or more files from a bucket. File Query Type Yes Required when the Is GridFS check box is selected. Specifies a query type when retrieving a file from a bucket. Select either of the following options: FIND_ONE: The Query Document activity retrieves a file by the filename and only one file can be searched for at each time. FIND_MANY: The Query Document activity retrieves a file by field values, and files containing the specified field values are returned.

46 30 Chapter 3 MongoDB Palette Input The Input tab contains the following fields. Table 9 MongoDB Query Documents Input (Sheet 1 of 3) Field Data Type CollectionName String (Optional) Name of the collection on which you want to execute a query operation. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. The value specified in this field takes precedence over the value specified in the Collection Name field of the Configuration tab. QueryDocument JSONString (Optional) A query condition document used to retrieve a document or documents from a collection. If no documents are specified in this field, the query operation will return all documents in the specified collection. ReturnFieldsDoc ument JSONString (Optional) A document used to limit the fields to be returned in all matching documents. If no documents are specified in this field, all fields in matching documents are returned. SortDocument JSONString (Optional) A document used to define the display order of the documents in the output result. Skip Integer (Optional) The number of documents to be skipped before the output result is displayed. Limit Integer (Optional) The maximum number of documents to be displayed in the output result for each query execution. The following field is displayed only when you select FIND_MANY from the Query Type list in the Configuration tab. HintDocument JSONString (Optional) A document which contains an index name or index specification and is used to override the default index in a collection.

47 Query Documents 31 Table 9 MongoDB Query Documents Input (Sheet 2 of 3) Field Data Type The following field is displayed only when you select DISTINCT from the Query Type list in the Configuration tab. DistinctField JSONString (Required) A document used to retrieve distinct values of a field. The following field is displayed only when you select AGGREGATE from the Query Type list in the Configuration tab. Document JSONString (Required) A document which contains an aggregation pipeline or a map-reduce operation and is used to execute an aggregation on a collection. For more information about defining an aggregation pipeline or a map-reduce operation, refer to tion/. The following fields are displayed when the Is GridFS check box is selected in the Configuration tab. BucketName String (Optional) Name of the bucket from which you want to query one or more files. The default bucket name is fs. Note: A valid bucket name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. FileName String Required only when the FIND_ONE file query type is selected in the Configuration tab. The name of the file which you want to search for. GenerateNewFile String (Optional) This field is displayed when the FIND_ONE file query type is selected in the Configuration tab. The full path name of the file which you want to save the output result in.

48 32 Chapter 3 MongoDB Palette Table 9 MongoDB Query Documents Input (Sheet 3 of 3) Field Data Type QueryDocument JSONString Required only when the FIND_MANY file query type is selected in the Configuration tab. A query condition document used to retrieve files from a bucket. Output The Output tab contains the following fields. Table 10 MongoDB Query Documents Output Field Data Type The following field is displayed only when you select FIND_ONE from the Query Type list in the Configuration tab. Document JSONString The first document matching the query condition. The following fields are displayed only when you select FIND_MANY from the Query Type list in the Configuration tab. Document JSONString All documents matching the query condition, or an empty set if no documents match the query condition. TotalCount Integer The total number of documents matching the query condition in the specified collection. RemainingCount Integer The total number of documents matching the query condition but are not displayed in the output result. The following field is displayed only when you select COUNT from the Query Type list in the Configuration tab. Count Integer The total number of documents matching the query condition in the specified collection. The following field is displayed only when you select DISTINCT from the Query Type list in the Configuration tab. Object JSONString A document which contains an array of distinct values of the specified field.

49 Query Documents 33 Table 10 MongoDB Query Documents Output (Cont d) Field Data Type The following field is displayed only when you select AGGREGATE from the Query Type list in the Configuration tab. Document JSONString A document which contains the aggregation result of the map-reduce operation or aggregation pipeline. The following fields are displayed when the Is GridFS check box is selected in the Configuration tab. Document JSONString Displayed when the FIND_ONE file query type is selected in the Configuration tab. A document which contains a file matching the file query condition. QueryFileContent Stream FileOutput Java Object Displayed only when the FIND_ONE file query type is selected in the Configuration tab. An Instance of a file stream returned by the Query Documents activity. Document JSONString Displayed when the FIND_MANY file query type is selected in the Configuration tab. Documents which contain the files matching the file query condition. QueryFileContent Stream Java Object Displayed when the FIND_MANY file query type is selected in the Configuration tab. An Instance of a file stream returned by the Query Documents activity.

50 34 Chapter 3 MongoDB Palette Error Output The Error Output tab contains the following fields. Table 11 MongoDB Query Documents Exceptions Error Schema Element Data Type MongoDBPluginException msg String This error message is displayed when the MongoDB plug-in captures an exception for the Query Documents activity. msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Query Documents activity. MongoException msg String This error message is displayed when the MongoDB encounters internal errors. msgcode String This error code is displayed when the MongoDB encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code when a network-related exception occurs. JSONParseException msg String This error message is displayed when an invalid JSON object is passed to the JSON parser. msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser. CursorNotFoundException msg String This error message is displayed when a cursor is not found. msgcode String This error message is displayed when a cursor is not found.

51 Query Documents 35 Fetching Subsets of the Result Set When the FIND_MANY query type is selected and the result set of a query is very large, you can retrieve subsets of the result set and iterate until the entire result set is processed. To retrieve subsets, you can use a Repeat-Until-True loop group to iterate until the entire result set is processed. Use the following procedure as a guideline for creating your Repeat-Until-True loop group. 1. Create a Query Documents activity. 2. Select FIND_MANY as the query type and configure the required fields in the Configuration tab. 3. Set the Skip and Limit input items of the Query Documents activity to the number of documents you want to skip and the maximum number of documents that can be displayed in each execution of the loop respectively. 4. Select the Query Documents activity, and click the icon on the toolbar to create a group containing the activity. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about working with groups. 5. In the Configuration tab of the created group, select While true as the group action, and specify an index name (for example, i). 6. The loop should exit when the entire result set are consumed, that is, the value of the RemainingCount element in the Output tab is equal to 0 (zero). Therefore, the loop condition could be set as the following: $QueryDocuments/QueryActivityResult/RemainingCount = 0 The procedure above is a general guideline for creating a loop group to process a large set of documents. You can modify the procedure to include additional processing of the documents. Examples The following example shows you how to use the loop condition The example is based on the following assumptions: There are 20 documents in total that match the query condition. The Skip field value is set to (i-1)*5. The Limit field value is set to 5. The following table lists the query result in each loop process.

52 36 Chapter 3 MongoDB Palette Table 12 Example of Fetching Subsets of the Result Set Total Documents Skipped Documents Returned Documents Remaining Count The first loop (i=1) 20 No documents are skipped. The second loop (i=2) 20 Documents ranking from 1 to 5 are skipped. The third loop (i=3) 20 Documents ranking from 1 to 10 are skipped. The fourth loop (i=4) 20 Documents ranking from 1 to 15 are skipped. Documents ranking from 1 to 5 are displayed in the output result. Documents ranking from 6 to 10 are displayed in the output result. Documents ranking from 11 to 15 are displayed in the output result. Documents ranking from 16 to 20 are displayed in the output result The loop exits because the loop condition evaluates to true.

53 Update Document 37 Update Document Activity The Update Document activity supports the following functionalities: Changes specific field values in an existing document or documents in a collection. Replaces an existing document completely in a collection. Inserts a new document into a collection if no documents match the update specification. Configuration The Configuration tab contains the following fields. Table 13 MongoDB Update Document Configuration (Sheet 1 of 3) Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Update Document. No (Optional) A brief description of the activity. Click and add the description in the dialog. MongoDB Connection Collection Name Yes Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity. (Required) Name of the collection on which you want to execute a update operation. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted.

54 38 Chapter 3 MongoDB Palette Table 13 MongoDB Update Document Configuration (Sheet 2 of 3) Field Write Concern Global Variable? Yes (Required) Specifies an assurance that MongoDB provides when reporting on the success of a write operation. Note: The strength of a write concern determines the level of an assurance. When performing a write operation which has a weak write concern, the write operation returns quickly. While performing a write operation with a strong write concern, the client will wait for the MongoDB to confirm the write operation before reporting the result the operation. MongoDB provides the following levels of write concern, listed from the weakest to strongest: UNACKNOWLEDGED: With an unacknowledged write concern, MongoDB does not acknowledge the receipt of a write operation and the write operation returns as soon as the message is written to the socket. Only network errors are captured and handled. ACKNOWLEDGED: With a receipt acknowledged write concern, a write operation waits for an acknowledgement from the primary server before returning a result. Network, duplicate key, and other errors are captured and handled. JOURNALED: With a journaled write concern, MongoDB acknowledges a write operation after committing the data to the journal. Both network issues and server errors are captured and handled. This type of write concern ensures that MongoDB can recover the data if there is a shutdown or power interruption emergency. Before using this type of write concern, you must have journaling enabled. FSYNCED: With a fsynced write concern, a write operation waits for the server to flush data to the disk before returning a result. Network, duplicate key, and other errors are captured and handled. REPLICA_ACKNOWLEDGED: With a replica acknowledged write concern, a write operation waits for acknowledgements from at least 2 servers before returning a result. Network, duplicate key, and other errors are captured and handled. MAJORITY: With a majority write concern, a write operation waits for acknowledgements from a majority of servers before returning a result. Network, duplicate key, and other errors are captured and handled.

55 Update Document 39 Table 13 MongoDB Update Document Configuration (Sheet 3 of 3) Field Continue On Error Global Variable? Boolean (Optional) A parameter which controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. When the check box is selected, MongoDB continues to process the remaining write operations if an error occurs when processing one of the write operations. Input The Input tab contains the following fields. Table 14 MongoDB Update Document Input Field Data Type CollectionName String (Optional) Name of the collection on which you want to execute the update operation. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. The value specified in this field takes precedence over the value specified in the Collection Name field of the Configuration tab. QueryDocument JSONString (Required) An update specification document used to match a document or documents to be updated. UpdateDocument JSONString (Required) A document used to update the document or documents matching the update specification.

56 40 Chapter 3 MongoDB Palette Table 14 MongoDB Update Document Input (Cont d) Field Data Type Upsert Boolean (Optional) A parameter that decides whether to insert the document into a collection if no documents match the update specification. A valid value for this field is 1 (true) or 0 (false). The default value for this field is 0 (false). If you set this field value to 1 (true), the document specified in the UpdateDocument field will be inserted into the specified collection if no documents match the update specification. Multi Boolean (Optional) A parameter that decides whether the update operation applies to all documents matching the update specification. A valid value for this field is 1 (true) or 0 (false). The default value for the field is 0 (false). If you set this field value to 1 (true), all documents matching the update specification will be updated, or only the first document matching the update specification will be updated. ContinueOnError Boolean (Optional) A parameter that controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. A valid value of this field is 1 (true) or 0 (false). The default value is 0 (false). The value specified in this field takes precedence over the value given in the Continue On Error field of the Configuration tab. Output The Output tab contains the following fields. Table 15 MongoDB Update Document Output Field Data Type ResultDocument JSONString A document which records the status of the Update Documents activity. SucceedNum Integer The total number of existing documents which you successfully updated in the specified collection.

57 Update Document 41 Table 15 MongoDB Update Document Output (Cont d) Field Data Type FailedNum Integer The total number of existing documents which you failed to update in the specified collection. Upserts JSONString The new document or documents you successfully inserted into the collection. Error Output The Error Output tab contains the following fields. Table 16 MongoDB Update Document Exceptions Error Schema Element Data Type MongoDBPluginException msg String This error message is displayed when the MongoDB plug-in captures an exception for the Update Document activity. msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Update Document activity. MongoException msg String This error message is displayed when MongoDB encounters internal errors. msgcode String This error code is displayed when MongoDB encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code when a network-related exception occurs. JSONParseException msg String This error message is displayed when an invalid JSON object is passed to the JSON parser.

58 42 Chapter 3 MongoDB Palette Table 16 MongoDB Update Document Exceptions (Cont d) Error Schema Element Data Type msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser.

59 Remove Document 43 Remove Document Activity The Remove Document activity supports the following functionalities:. Deletes a single document matching a query condition from a collection. Deletes all documents from a collection Deletes a single file matching a file query condition from a bucket. Deletes all files from a bucket. Batch operations. You can delete all documents matching a query condition from a collection or delete all files matching a file query condition from a bucket at each time. Configuration The Configuration tab contains the following fields. Table 17 MongoDB Remove Document Configuration (Sheet 1 of 3) Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Remove Document. No (Optional) A brief description of the activity. Click and add the description in the dialog. MongoDB Connection Collection Name Yes Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity. (Required) Name of the collection which you want to remove documents from. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted.

60 44 Chapter 3 MongoDB Palette Table 17 MongoDB Remove Document Configuration (Sheet 2 of 3) Field Write Concern Global Variable? Yes (Required) Specifies an assurance that MongoDB provides when reporting on the success of a write operation. Note: The strength of a write concern determines the level of an assurance. When performing a write operation which has a weak write concern, the write operation returns quickly. While performing a write operation with a strong write concern, the client will wait for the MongoDB to confirm the write operation before reporting the result the operation. MongoDB provides the following levels of write concern, listed from the weakest to strongest: UNACKNOWLEDGED: With an unacknowledged write concern, MongoDB does not acknowledge the receipt of a write operation and the write operation returns as soon as the message is written to the socket. Only network errors are captured and handled. ACKNOWLEDGED: With a receipt acknowledged write concern, a write operation waits for an acknowledgement from the primary server before returning a result. Network, duplicate key, and other errors are captured and handled. JOURNALED: With a journaled write concern, MongoDB acknowledges a write operation after committing the data to the journal. Both network issues and server errors are captured and handled. This type of write concern ensures that MongoDB can recover the data if there is a shutdown or power interruption emergency. Before using this type of write concern, you must have journaling enabled. FSYNCED: With a fsynced write concern, a write operation waits for the server to flush data to the disk before returning a result. Network, duplicate key, and other errors are captured and handled. REPLICA_ACKNOWLEDGED: With a replica acknowledged write concern, a write operation waits for acknowledgements from at least 2 servers before returning a result. Network, duplicate key, and other errors are captured and handled. MAJORITY: With a majority write concern, a write operation waits for acknowledgements from a majority of servers before returning a result. Network, duplicate key, and other errors are captured and handled.

61 Remove Document 45 Table 17 MongoDB Remove Document Configuration (Sheet 3 of 3) Field Continue On Error Global Variable? Boolean (Optional) A parameter which controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. When the check box is selected, MongoDB continues to process the remaining write operations if an error occurs when processing one of the write operations. Is GridFS Yes (Optional) GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB. Select this check box if you want to remove one or more files from a bucket. Input The Input tab contains the following fields. Table 18 MongoDB Remove Document Input Field Data Type CollectionName String (Optional) Name of the collection which you want to delete documents from. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. The value specified in this field takes precedence over the value specified in the Collection Name field of the Configuration tab. QueryDocument JSONString (Required) A remove specification document used to match a document or documents to be removed.

62 46 Chapter 3 MongoDB Palette Table 18 MongoDB Remove Document Input (Cont d) Field Data Type ContinueOnError Boolean (Optional) A parameter that controls whether MongoDB will continue to process the remaining write operations if an error occurs when processing one of the write operations. A valid value of this field is 1 (true) or 0 (false). The default value is 0 (false). The value specified in this field takes precedence over the value given in the Continue On Error field of the Configuration tab. Multi Boolean (Optional) A parameter that decides whether the remove operation applies to all documents matching the remove specification. A valid value for this field is 1 (true) or 0 (false). The default value for the field is 0 (false). If you set this field value to 1 (true), all documents matching the remove specification will be removed, or only the first document matching the remove specification will be removed. The following fields are displayed when the Is GridFS check box is selected in the Configuration tab. BucketName String (Optional) Name of the bucket from which you want to delete a file or files. The default bucket name is fs. Note: A valid bucket name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. QueryDocument JSONString (Required) A remove specification document used to match a file or files to be deleted.

63 Remove Document 47 Output The Output tab contains the following field. Table 19 MongoDB Remove Document Output Field Data Type ResultDocument JSONString A document which records the status of the Remove Document activity. SucceedNum Integer The total number of documents which you successfully removed from the specified collection. FailedNum Integer The total number of documents which you failed to remove from the specified collection. Error Output The Error Output tab contains the following fields. Table 20 MongoDB Remove Document Exceptions Error Schema Element Data Type MongoDBPluginException msg String This error message is displayed when the MongoDB plug-in captures an exception for the Remove Document activity. msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Remove Document activity. MongoException msg String This error message is displayed when the MongoDB encounters internal errors. msgcode String This error code is displayed when the MongoDB encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code when a network-related exception occurs.

64 48 Chapter 3 MongoDB Palette Table 20 MongoDB Remove Document Exceptions (Cont d) Error Schema Element JSONParseException Data Type msg String This error message is displayed when an invalid JSON object is passed to the JSON parser. msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser.

65 Get MongoDB Connection 49 Get MongoDB Connection Activity The Get MongoDB Connection activity supports obtaining a MongoDB Connection reference from a specific connection pool and utilizing it in a custom Java Code activity. Configuration The Configuration tab contains the following fields. Table 21 MongoDB Get MongoDB Connection Configuration Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Get MongoDB Connection. No (Optional) A brief description of an activity. Click and add the description in the dialog. MongoDB Connection Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity. Input The Get MongoDB Connection requires no input.

66 50 Chapter 3 MongoDB Palette Output The Output tab contains the following field. Table 22 MongoDB Get MongoDB Connection Output Field Data Type MongoDBConne ctionaccessor Java Object An instance of the MongoDB connection obtained from the Get MongoDB Connection activity. The following is the definition of the instance: package com.tibco.plugin.mongodb.connection; import com.mongodb.db; public interface MongoDBConnectionAccessor { public DB getdatabase(); } Error Output The Error Output tab contains the following fields. Table 23 MongoDB Get MongoDB Connection Exceptions Error Schema Data Type Element MongoDBPluginException msg String This error message is displayed when the MongoDB plug-in captures an exception for the Get MongoDB Connection activity. msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Get MongoDB Connection activity. MongoException msg String This error message is displayed when the MongoDB encounters internal errors. msgcode String This error code is displayed when the MongoDB encounters internal errors. NetworkException

67 Get MongoDB Connection 51 Table 23 MongoDB Get MongoDB Connection Exceptions (Cont d) Error Schema Element Data Type msg String This error message is displayed when a network-related exception occurs. msgcode String This error code when a network-related exception occurs.

68 52 Chapter 3 MongoDB Palette Database Command Activity The Database Command activity supports executing custom database commands on a target MongoDB database. For more information about the commands that MongoDB supports, refer to Configuration The Configuration tab contains the following fields. Table 24 MongoDB Database Command Configuration Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Database Command. No (Optional) A brief description of an activity. Click and add the description in the dialog. MongoDB Connection Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity.

69 Database Command 53 Table 24 MongoDB Database Command Configuration (Cont d) Field Read Preference Global Variable? Yes (Required) Determines how the client directs read operations to the members of a replica set. Select one option from the following list: PRIMARY: The default mode. Operations read from the primary member of a replica set. PRIMARY_PREFERRED: Operations read from the primary member preferentially, but if the primary member is unavailable, operations read from secondary members of a replica set. SECONDARY: Operations read from secondary members of a replica set. SECONDARY_PREFERRED: Operations read from secondary members preferentially, but if no secondary members are available, operations read from the primary member of a replica set. NEAREST: Operations read from a member of a replica set with the least network latency, irrespective of the member type of the replica set. Input The Input tab contains the following field. Table 25 MongoDB Database Command Input Field Data Type Document JSONString (Required) A document which contains the database command you want to execute.

70 54 Chapter 3 MongoDB Palette Output The Output tab contains the following field. Table 26 MongoDB Database Command Output Field Data Type ResultDocument JSONString A document which records the status of the Database Command activity. Error Output The Error Output tab contains the following fields. Table 27 MongoDB Database Command Exceptions Field Data Type MongoDBPluginException msg String This captured an exception message is displayed when the MongoDB plug-in captures an exception for the Database Command activity. msgcode String This error code is displayed when the MongoDB plug-in captures an exception for the Database Command activity. MongoException msg String This error message is displayed when the MongoDB encounters internal errors. msgcode String This error code is displayed when the MongoDB encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code is displayed when a network-related exception occurs. JSONParseException

71 Database Command 55 Table 27 MongoDB Database Command Exceptions (Cont d) Field Data Type msg String This error message is displayed when an invalid JSON object is passed to the JSON parser. msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser.

72 56 Chapter 3 MongoDB Palette Map-Reduce Activity The Map-Reduce activity supports the performance of map and reduce operations, as well as the optional finalize operation to execute aggregations on a collection by using custom JavaScript functions. In general, a map-reduce operation contains the following required phases: Map phase In this phase, the map-reduce operation processes each document and emits one or more objects for each input document. Reduce phase In this phase, the map-reduce operation combines the output of the map operation. Optionally, a map-reduce operation can have a finalize phase to make final modifications to the result. Like other aggregation operations, a map-reduce operation allows you to specify a query condition to select the input documents as well as limit and sort the returned results. Configuration The Configuration tab contains the following fields. Table 28 MongoDB Map-Reduce Configuration (Sheet 1 of 3) Field Global Variable? Name No (Required) Name of the activity in the process definition. The default value is Map-Reduce. No (Optional) A brief description of an activity. Click and add the description in the dialog. MongoDB Connection Yes (Required) Specifies a shared connection resource. Click Browse resources to open the Select a Resource dialog. All available resources are listed in the dialog. Select one to apply to your current activity.

73 Map-Reduce 57 Table 28 MongoDB Map-Reduce Configuration (Sheet 2 of 3) Field Collection Name Read Preference Global Variable? Yes Yes (Required) Name of the collection on which you want to perform a map-reduce operation. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. (Required) Determines how the client directs read operations to the members of a replica set. Select one option from the following list: PRIMARY: The default mode. Operations read from the primary member of a replica set. PRIMARY_PREFERRED: Operations read from the primary member preferentially, but if the primary member is unavailable, operations read from secondary members of a replica set. SECONDARY: Operations read from secondary members of a replica set. SECONDARY_PREFERRED: Operations read from secondary members preferentially, but if no secondary members are available, operations read from the primary member of a replica set. NEAREST: Operations read from a member of a replica set with the least network latency, irrespective of the member type of the replica set. Map Function Yes (Required) A JavaScript function that associates or maps a value with a key and emits the key and value pair. Click to add your java script in the Map Function dialog. Reduce Function Yes (Required) A JavaScript function that makes all values of a single object associated with a particular key. Click to add your java script in the Reduce Function dialog.

74 58 Chapter 3 MongoDB Palette Table 28 MongoDB Map-Reduce Configuration (Sheet 3 of 3) Field Finalize Function Global Variable? Yes (Optional) A JavaScript function follows the reduce method and is used to modify the output result. Click to add your java script in the Finalize Function dialog. Input The Input tab contains the following fields. Table 29 MongoDB Map-Reduce Input Field Data Type CollectionName String (Optional) Name of the collection on which you want to execute a map-reduce operation. Note: A valid collection name adheres to the following rules: Starts with a letter or a digit. Consists of alphanumeric characters. En dash (-) and underscore(_) are permitted. The value specified in this field takes precedence over the value specified in the Collection Name field of the Configuration tab. JavaScriptMapFu nction JavaScriptReduce Function JavaScriptFinalize Function Java Script Java Script Java Script (Optional) Customs a JavaScript to associate or map a value with a key and emit the key and value pair. The value specified in this field takes precedence over the value specified in the Map Function field of the Configuration tab. (Optional ) Customs a JavaScript to make all values of a single object associated with a particular key. The value specified in this field takes precedence over the value specified in the Reduce Function field of the Configuration tab. (Optional) Customs a JavaScript following the reduce method to modify the output result. The value specified in this field takes precedence over the value specified in the Finalize Function field of the Configuration tab.

75 Map-Reduce 59 Table 29 MongoDB Map-Reduce Input (Cont d) Field Data Type OutputTarget String Required only when the output type for the map-reduce operation is REPLACE, MERGE, and REDUCE. Specifies a collection to store map-reduce operation results. If no collections are specified in this field, a temp collection will be used to store map-reduce operation results. OutputType String (Required) Specifies where a map-reduce operation result will be stored. Select one from the following options: INLINE: The map-reduce operation returns the result inline. REPLACE: The map-reduce operation writes the result to a specified collection and you can perform subsequent map-reduce operations on the same collection. The previous result generated by the old map-reduce operations will be replaced with the new map-reduce operations result. MERGE: The map-reduce operation writes the result to a specified collection and you can perform subsequent map-reduce operations on the same collection. The previous result generated by the old map-reduce operations will be merged by the new map-reduce operations result. REDUCE: The map-reduce operation writes the result to a specified collection and you can perform subsequent map-reduce operations on the same collection. The previous result generated by the old map-reduce operations will be reduced by the new map-reduce operations result. QueryDocument JSONString (Optional) A query condition document used to match documents to be mapped and reduced. Limit Integer (Optional) The maximum number of documents to be displayed in the output result for each query execution. SortDocument JSONString (Optional) A document used to define the display order of the documents in the output result.

76 60 Chapter 3 MongoDB Palette Output The Output tab contains the following field. Table 30 MongoDB Map-Reduce Output Field Data Type ResultDocu JSONString A document which records the status of the Map-Reduce activity. ment The document varies when you select different output type. Error Output The Error Output tab contains the following fields. Table 31 MongoDB Map-Reduce Exceptions Error Schema Element MongoDBPluginException Data Type msg String This error message is displayed when the MongoDB plug-in captures an exception for the Map-Reduce activity. msgcode String This error message is displayed when the MongoDB plug-in captures an exception for the Map-Reduce activity. MongoException msg String This error message is displayed when the MongoDB plug-in encounters internal errors. msgcode String This error code is displayed when the MongoDB plug-in encounters internal errors. NetworkException msg String This error message is displayed when a network-related exception occurs. msgcode String This error code is displayed when a network-related exception occurs. JSONParseException

77 Map-Reduce 61 Table 31 MongoDB Map-Reduce Exceptions (Cont d) Error Schema Element Data Type msg String This error message is displayed when an invalid JSON object is passed to the JSON parser. msgcode String This error code is displayed when an invalid JSON object is passed to the JSON parser.

78 62 Chapter 3 MongoDB Palette

79 63 Chapter 4 Working with Sample Projects This chapter describes the sample projects packaged with TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB. Working through the sample projects helps you understand how TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB works. Topics Overview of Sample Projects, page 64 Hierarchical-Aggregation Project, page 65 Metadata_and_Asset_Management Project, page 71

80 64 Chapter 4 Working with Sample Projects Overview of Sample Projects TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB packages sample projects within the installer. The sample projects are located in the TIBCO_HOME\bw\plugins\mongodb\samples directory. The plug-in packages the following sample projects: Hierarchical-Aggregation Project, page 65 Metadata_and_Asset_Management Project, page 71

81 Hierarchical-Aggregation Project 65 Hierarchical-Aggregation Project The Hierarchical-Aggregation project contains the following main processes and subprocesses: Main Processes Include MapReduceAggregate Process, QueryAggregate Process, and QueryDocuments Process. Subprocesses Include Clean Insert Documents Subprocess and Insert Document Subprocess. MapReduceAggregate Process The MapReduceAggregate process mainly demonstrates the following: How to insert a group of documents into a specific collection. How to execute a map-reduce operation on a specific collection. How to obtain a MongoDB Connection reference and utilize it to get information related to another collection. Figure 5 MapReduceAggregate Process The activities contained in the process are described in Table 32. Table 32 MapReduceAggregate Process Activities Activity Start Clean Documents Starts the process. Invokes the Clean Insert Documents subprocess to clean all documents in the samplecollection collection. See Clean Insert Documents Subprocess on page 68 for more detailed information about the Clean Insert Documents subprocess.

82 66 Chapter 4 Working with Sample Projects Table 32 MapReduceAggregate Process Activities (Cont d) Activity Insert Documents Map-Reduce Get DataBase Connection Get Result Get Collection Info(Command) End Invokes the Insert Document subprocess to insert a group of documents into the samplecollection collection at each time. See Insert Document Subprocess on page 69 for more detailed information about the Insert Document subprocess. Performs a map-reduce operation on the samplecollection collection and writes the result of the operation into the resultcollection collection. Obtains a MongoDB Connection reference. Utilizes the obtained Connection reference to get information related to the resultcollection collection and perform a query operation on this collection. Obtains information related to the samplecollection collection. Ends the process. QueryAggregate Process The QueryAggregate process mainly demonstrates how to execute an AGGREGATE query on a specific collection. Figure 6 QueryAggregate Process

83 Hierarchical-Aggregation Project 67 The activities contained in the process are described in Table 33. Table 33 QueryAggregate Process Activities Activity Start Clean Documents Insert Documents AggregateQuery QueryError End Starts the process. Invokes the Clean Insert Documents subprocess to clean all documents in the samplecollection collection. See Clean Insert Documents Subprocess on page 68 for more detailed information about the Clean Insert Documents subprocess. Invokes the Insert Document subprocess to insert a group of documents into the samplecollection collection at each time. See Insert Document Subprocess on page 69 for more detailed information about the Insert Document subprocess. Executes an aggregation on the samplecollection collection by using the $match pipeline. Raises an error if the AggregateQuery activity fails. Ends the process. QueryDocuments Process The QueryDocuments process mainly demonstrates how to execute a FIND_MANY query on a specific collection. Figure 7 QueryDocuments Process

84 68 Chapter 4 Working with Sample Projects The activities contained in the process are described in Table 34. Table 34 QueryDocuments Process Activities Activity Start Clean Documents Insert Documents Group Starts the process. Invokes the Clean Insert Documents subprocess to clean all documents in the samplecollection collection. See Clean Insert Documents Subprocess on page 68 for more detailed information about the Clean Insert Documents subprocess. Invokes the Insert Document subprocess to insert a group of documents into the samplecollection collection simultaneously. See Insert Document Subprocess on page 69 for more detailed information about the Insert Document subprocess. The Query Documents activity queries documents from the samplecollection collection iteratively and returns one document at each time. The Write File activity writes each document returned from the Query Documents activity into the output.txt file which is located in the D:\ directory. End Ends the process. Clean Insert Documents Subprocess The Clean Insert Documents subprocess demonstrates how to clean all documents in a specific collection. Figure 8 Clean Insert Documents Subprocess

85 Hierarchical-Aggregation Project 69 The activities contained in the subprocess are described in Table 35. Table 35 Clean Insert Documents Subprocess Activities Activity Start Clean Insert Documents Clean Output Documents End Starts the subprocess. Deletes all documents inserted by the Insert Document activity or Updated Document activity from the samplecollection collection. Deletes all documents generated by the Map-Reduce activity from the samplecollection collection. Ends the subprocess. Insert Document Subprocess The Insert Document subprocess demonstrates how to insert a group of documents into a specific collection in the batch mode. Figure 9 Insert Document Subprocess The activities contained in the subprocess are described in Table 36. Table 36 Insert Document Subprocess Activities Activity Start Insert Document End Starts the subprocess. Inserts a group of documents into the samplecollection collection in the batch mode. Ends the subprocess. Setting Up the Project Before running the project, you are required to perform the following steps to set up the project in TIBCO Designer.

86 70 Chapter 4 Working with Sample Projects 1. Start TIBCO Designer. 2. Click Open existing project in the Project tab of the TIBCO Designer dialog. 3. Click next to the Project Directory field in the Open Project dialog and then navigate to the Hierarchical-Aggregation folder, which is located in the TIB_bwpluginmongodb_HOME/samples directory. Click OK. The Hierarchical-Aggregation project is displayed in the Project panel. 4. Create a user to log into the MongoDB database. a. Expand the SharedResource folder of the opened project. b. Click the config file and then copy the command in the Text field of the Configuration tab. c. Navigate to the command line where you run the mongo process, paste the command and run it. The Successfully added user: {"user": "sampleu", "roles" : ["readwrite "] } message is displayed on the command line after running the command. 5. Click Test Connection in the Configuration tab of the MongoDB Connection to validate the connection. 6. Click Project > Save from to save the project. Running the Project After setting up the project, complete the following steps to trigger a process contained in the project: 1. In the Project panel, click Start testing viewed process in the Tester tab. 2. In the Select Processes to Load dialog, select the check box next to the process you want to run and then click Load Selected. When a process is executed in the Test mode, the black transition arrows pointing to each activity turn green. 3. Click Stop testing to stop testing and return to the Design mode. For detailed information on using the Test mode and setting breakpoints, see TIBCO ActiveMatrix BusinessWorks Process Design, Chapter 18, "Testing Process Definitions."

87 Metadata_and_Asset_Management Project 71 Metadata_and_Asset_Management Project The Metadata_and_Asset_Management project contains the following main processes and subprocesses: Main Processes Include the RESTDelete Process, RESTServices Process, Query JSON to XML Process, Save XML to MongoDB Process, GridFS Photo Operate Process, and Query by Index Process. Subprocesses The subprocesses can be divided into the following groups: Create: Includes the Create Documents Subprocess and Create GridFS File Subprocess. Delete: Includes the Delete Document Subprocess and Delete Photo Subprocess. Read: Includes the Query Document Subprocess, Query GridFS Photos Subprocess, and Query Many Documents Subprocess. Run Command: Includes the Drop Index Subprocess. Update: Includes the Update Document Subprocess. This sample project contains activities in the REST and JSON palette which is a component of TIBCO ActiveMatrix BusinessWorks Plug-in for REST and JSON. Before running this sample project, you must install TIBCO ActiveMatrix BusinessWorks Plug-in for REST and JSON version or higher. For more information about how to install TIBCO ActiveMatrix BusinessWorks Plug-in for REST and JSON, refer to TIBCO ActiveMatrix BusinessWorks Plug-in for REST and JSON Installation. RESTDelete Process The RESTDelete process demonstrates how to invoke RESTful web services API and receive responses from Service Provider. Figure 10 RESTDelete Process

88 72 Chapter 4 Working with Sample Projects Table 37 RESTDelete Process Activities The activities contained in the process are described in Table 37. Activity Start Invoke REST API Parse JSON End Starts the process. Invokes RESTful web services API and receives responses from Service Provider. Transforms JSON documents received from Service Provider into XML strings. Ends the process. RESTServices Process The RESTServices process demonstrates how to expose a TIBCO ActiveMatrix BusinessWorks process as a RESTful web service by binding a HTTP request to the BusinessWorks process. Figure 11 RESTServices Process Table 38 RESTServices Process Activities The activities contained in the process are described in Table 38. Activity HTTP Receiver REST Dispatch and Reply End Exposes the Delete Document subprocess as a RESTful web service after receiving the receipt of a HTTP request. Invokes the Delete Document subprocess to delete all documents from the nodes collection. See Delete Document Subprocess on page 78 for more information about the Delete Document subprocess. Ends the process.

89 Metadata_and_Asset_Management Project 73 Query JSON to XML Process The Query JSON to XML process demonstrates: How to delete, insert, query documents from a specific collection. How to transform documents into XML strings. Figure 12 Query JSON to XML Process The activities contained in the process are described in Table 39. Table 39 Query JSON to XML Process Activities Activity Start Delete Document Create Documents Query Many Documents Parse JSON Group End Starts the process. Invokes the Delete Document subprocess to delete all documents from the nodes collection. See Delete Document Subprocess on page 78 for more information about the Delete Document subprocess. Invokes the Create Documents subprocess to insert a group of documents into the nodes collection in the batch mode. See Create Documents Subprocess on page 77 for more information about the Create Documents subprocess. Invokes the Query Many Documents subprocess to query all documents from the nodes collection. See Query Many Documents Subprocess on page 81 for more information about the Query Many Documents subprocess. Transforms each document in the node collection into an XML string. Ends the process.

90 74 Chapter 4 Working with Sample Projects Save XML to MongoDB Process The Save XML to MongoDB process demonstrates: How to read a.xml file and transform the file into an XML schema tree. How to take an instance of an XML schema element and render it as an XML string. How to process an XML string and render it as a JSON string. How to insert a JSON string into a specific collection. Figure 13 Save XML to MongoDB Process The activities contained in the process are described in Table 40. Table 40 Save XML to MongoDB Process Activities Activity Start Delete Document Read File Parse XML Starts the process. Invokes the Delete Document subprocess to delete all documents from the nodes collection. See Delete Document Subprocess on page 78 for more information about the Delete Document subprocess. Reads the user.xml file which is located in the ProjectLocation/Resource directory and passes the binary file contents to the Parse XML activity. Takes the binary XML file and transforms it into an XML schema tree based on the XSD specified in the user.xsd file which is located in the ProjectLocation/Resource directory.

91 Metadata_and_Asset_Management Project 75 Table 40 Save XML to MongoDB Process Activities (Cont d) Activity Group The Render XML activity takes an instance of an XML schema element and renders it as a stream of bytes containing an XML string. The Render JSON activity processes the XML string received from the Render XML activity and renders it as a JSON string. The Create Documents activity inserts the JSON string received from the Render JSON activity into the nodes collection. End Ends the process. GridFS Photo Operate Process The GridFS Photo Operate process demonstrates how to insert, query, and delete a file from a specific bucket. Figure 14 GridFS Photo Operate Process The activities contained in the process are described in Table 41. Table 41 GridFS Photo Operate Process Activities Activity Start Create GridFS File Starts the process. Invokes the Create GridFS File subprocess to insert the MongoDB.jpg file into the assets bucket and specify Mongojpg as the new file name when inserting it into the bucket. See Create GridFS File Subprocess on page 78 for more information about the Create GridFS File subprocess.

92 76 Chapter 4 Working with Sample Projects Table 41 GridFS Photo Operate Process Activities (Cont d) Activity Query GridFS Photos Java Code Delete Photo End Invokes the Query GridFS Photos subprocess to query the Mongojpg.jpg file from the assets bucket. See Query GridFS Photos Subprocess on page 80 for more information about the Query GridFS Photos subprocess. Obtains an instance of the InputStream and writes the file stream into the photo.jpg file. Invokes the Delete Photo subprocess to delete the Mongojpg.jpg file from the assets bucket. See Delete Photo Subprocess on page 79 for more information about the Delete Photo subprocess. Ends the process. Query by Index Process The Query by Index process demonstrates how to query documents from a specific collection using a newly created index. Figure 15 Query by Index Process Table 42 Query by Index Process Activities The activities contained in the process are listed in the Table 42. Activity Start Delete Document Starts the process. Invokes the Delete Document subprocess to delete all documents from the nodes collection. See Delete Document Subprocess on page 78 for more information about the Delete Document subprocess.

93 Metadata_and_Asset_Management Project 77 Table 42 Query by Index Process Activities (Cont d) Activity Drop Index Invokes the Drop Index subprocess to delete all indexes in the nodes collection. See Drop Index Subprocess on page 82 for more information about the Drop Index subprocess. Create Documents Update Document Query Document End Invokes the Create Documents subprocess to insert a group of documents into the collection and create a new index on a single field in the nodes collection. See Create Documents Subprocess on page 77 for more information about the Create Documents subprocess. Invokes the Update Document subprocess to select a document and change a field value in the document. See Update Document Subprocess on page 83 for more information about the Update Document subprocess. Invokes the Query Document subprocess to query the updated document from the nodes collection using the newly created index. See Query Document Subprocess on page 80 for more information about the Query Document subprocess. Ends the process. Create Documents Subprocess The Create Documents subprocess demonstrates how to insert a group of documents into a specific collection in the batch mode. Figure 16 Create Documents Subprocess

94 78 Chapter 4 Working with Sample Projects The activities contained in the subprocess are described in Table 43. Table 43 Create Documents Subprocess Activities Activity Start Create Documents End Starts the subprocess. Inserts a group of documents into the nodes collection in the batch mode. Ends the process. Create GridFS File Subprocess The Greate GridFS File subprocess demonstrates how to insert a file into a specific bucket. Figure 17 Create GridFS File Subprocess The activities contained in the subprocess are described in Table 44. Table 44 Create GridFS File Subprocess Activities Activity Start Create GridFS File End Starts the subprocess. Inserts the MongoDB.jpg file into the assets bucket and specify the Mongojpg as the new file name when inserting it into the bucket. Ends the process. Delete Document Subprocess The Delete Document subprocess demonstrates how to delete all documents from a specific collection.

95 Metadata_and_Asset_Management Project 79 Figure 18 Delete Document Subprocess The activities contained in the subprocess are described in Table 45. Table 45 Delete Document Subprocess Activities Activity Start Delete Document End Starts the subprocess. Deletes all documents from the nodes collection. Ends the subprocess. Delete Photo Subprocess The Delete Photo subprocess demonstrates how to delete a file from a specific bucket. Figure 19 Delete Photo Subprocess The activities contained in the subprocess are described in Table 46. Table 46 Delete Photo Subprocess Activities Activity Start Delete Photo End Starts the subprocess. Deletes the Mongojpg.jpg file from the assets bucket. Ends the subprocess.

96 80 Chapter 4 Working with Sample Projects Query Document Subprocess The Query Document subprocess demonstrates how to query a document from a specific collection using a newly created index. Figure 20 Query Document Subprocess The activities contained in the subprocess are described in Table 47. Table 47 Query Document Subprocess Activities Activity Start Query Document Cannot Find Document End Starts the subprocess. Queries a document from the nodes collection using a newly created index. Raises an error if the Query Document activity fails. Ends the subprocess. Query GridFS Photos Subprocess The Query GridFS Photos subprocess demonstrates how to query a file from a specific bucket.

97 Metadata_and_Asset_Management Project 81 Figure 21 Query GridFS Photos Subprocess The activities contained in the subprocess are described in Table 48. Table 48 Query GridFS Photos Subprocess Activities Activity Start Query GridFS Photos Cannot Find Photos End Starts the subprocess. Queries the Mongojpg.jpg file from the assets bucket. Raises an error if the Query GridFS Photos activity fails. Ends the subprocess. Query Many Documents Subprocess The Query Many Documents subprocess demonstrates how to query multiple documents from a specific collection using a newly created index. Figure 22 Query Many Documents Subprocess

98 82 Chapter 4 Working with Sample Projects The activities contained in the subprocess are described in Table 49. Table 49 Query Many Documents Subprocess Activities Activity Start Query Many Documents Query Many Error End Starts the subprocess. Queries multiple documents from the nodes collection using a newly created index. Raises an error if the Query Many Documents activity fails. Ends the subprocess. Drop Index Subprocess The Drop Index subprocess demonstrates how to delete all indexes in a specific collection. Figure 23 Drop Index Subprocess Table 50 Drop Index Subprocess Activities The activities contained in the subprocess are described in Table 50. Activity Start Drop Index Drop Index Error End Starts the subprocess. Deletes all the indexes in the nodes collection. Raises an error if the Query Many Documents activity fails. Ends the subprocess.

99 Metadata_and_Asset_Management Project 83 Update Document Subprocess The Update Document subprocess demonstrates how to change a field value of a document in a specific collection. Figure 24 Update Document Subprocess The activities contained in the subprocess are described in Table 51. Table 51 Update Document Subprocess Activities Activity Start Update Document End Starts the subprocess. Changes a field value of a document. Ends the subprocess. Setting Up the Project Before running the project, you are required to perform the following steps to set up the project in TIBCO Designer. 1. Start TIBCO Designer. 2. Click Open existing project in the Project tab of the TIBCO Designer dialog. 3. Click next to the Project Directory field in the Open Project dialog, and then navigate to the Metadata_and_ Asset_Management folder, which is located in the TIB_bwpluginmongodb_HOME\samples directory. Click OK. The Metadata_and_ Asset_Management project is displayed in the Project panel.

100 84 Chapter 4 Working with Sample Projects 4. Change the value of the ProjectLocation global variable. a. Click the Global Variables tab in the Project panel. b. Click Open Advanced Editor at the upper-left corner of the Project panel. c. In the Global Variables dialog, expand MongoDB, change the value of the ProjectLocation parameter. The value should be as follows: TIB_bwpluginmongodb_HOME\samples\Metadata_and_ Asset_Management d. Click OK to save the global variable change. Running the Project After setting up the project, complete the following steps to trigger a process contained in the project: 1. In the Project panel, click Start testing viewed process in the Tester tab. 2. In the Select Processes to Load dialog, select the check box next to the process you want to run, and then click Load Selected. The RESTDelete and RESTServices processes must run simultaneously. When a process is executed in the Test mode, the black transition arrows pointing to each activity turn green. 3. Click Stop testing to stop testing and return to the Design mode. For detailed information on using the Test mode and setting breakpoints, see TIBCO ActiveMatrix BusinessWorks Process Design, Chapter 18, "Testing Process Definitions."

101 85 Appendix A Managing MongoDB Logs This appendix describes how to manage logs of TIBCO ActiveMatrix BusinessWorks Plug-in for MongoDB. Topics Managing Logs, page 86

102 86 Appendix A Managing MongoDB Logs Managing Logs Table 52 Log Properties Logs are used to trace and troubleshoot the plug-in exceptions at design time and runtime. You can specify the log level, the log file name, and the output destination for trace messages. To check log information, see log properties listed in Table 52. See the TIBCO ActiveMatrix BusinessWorks documentation for detailed information about logs. Property com.tibco.plugin.mongodb.debug The debug role properties of the plug-in. The default value is false. Only when bwengine property Trace.Debug.*=true and com.tibco.plugin.mongodb.debug=true, debug level information is logged. com.tibco.plugin.mongodb.info The info role properties of the plug-in. The default value is false. Only when bwengine property Trace.Info.*=true and com.tibco.plugin.mongodb.info=true, info level information is logged. com.tibco.plugin.mongodb.error The error role properties of the plug-in. The default value is true. Only when bwengine property Trace.Error.*=true and com.tibco.plugin.mongodb.error=true, error level information is logged.

103 87 Appendix B Error Codes This appendix describes the error codes that can be returned by the activities within the MongoDB palette. Topics Error Codes, page 88

104 88 Appendix B Error Codes Error Codes Table 53 Error Codes (Sheet 1 of 3) The exceptions thrown by the plug-in and corresponding descriptions and resolutions are listed in Table 53. Error Code Role Category Resolution BW-MONGODB Connection test failed: [%1 %2]. errorrole BW_Plug-in Unable to establish a connection to the server. Check if the MongoDB database server is started or the configuration of the specified MongoDB Connection shared resource is correct. BW-MONGODB Exception occurred while trying to obtain MongoDB connection reference [%1]: %2. errorrole BW_Plug-in Unable to get the MongoDB Connection referenced by the current activity. Check if the configuration of the MongoDB Connection referenced by the activity is correct. BW-MONGODB The MongoDB connection [%1] not found in repository. errorrole BW_Plug-in The repository does not contain the MongoDB Connection referenced by the current activity. Check if configuration of the MongoDB Connection referenced by the activity is correct. BW-MONGODB GridFS operate error: [%1]. errorrole BW_Plug-in An error occurs when using the GridFS function in the Insert Document, Query Documents, or Remove Document activity. Check error(s) listed in the error message and take appropriate action.

105 Error Codes 89 Table 53 Error Codes (Sheet 2 of 3) Error Code Role Category Resolution BW-MONGODB Input element value error: [%1]. errorrole BW_Plug-in An error occurs when you input an invalid value for a plug-in activity. Check error(s) listed in the error message and take appropriate action. BW-MONGODB Error while retrieving MongoDB connection from the pool: [%1], [%2 ]. BW-MONGODB BW-MONGODB errorrole BW_Plug-in An error occurs when retrieving a MongoDB Connection for a plug-in activity. Failed to recover connection: [%1]. errorrole BW_Plug-in Unable to recover a MongoDB Shared connection. Activity operate error: [%1]. errorrole BW_Plug-in An error occurs when running a plug-in activity. Check if the MongoDB database server is started or the configuration of the specified MongoDB Connection shared resource is correct. Check if the MongoDB database server is started or the configuration of the specified MongoDB Connection shared resource is correct. Check if the MongoDB database server is started or the configuration of the specified MongoDB Connection shared resource is correct. BW-MONGODB Data Conversion error. Exception occurred while trying to convert XML data to Java object.[%1] errorrole BW_Plug-in An error occurs when retrieving an input value of a plug-in activity. Check error(s) listed in the error message and take appropriate action.

106 90 Appendix B Error Codes Table 53 Error Codes (Sheet 3 of 3) Error Code Role Category Resolution BW-MONGODB Activity input data conversion error. Exception [%1] occurred while trying to render the activity input data.[%2] errorrole BW_Plug-in The current activity is not able to convert the input data. Check error(s) listed in the error message and take appropriate action. BW-MONGODB BW-MONGODB Configuration error in field [ %1 ] the value must be non empty. errorrole BW_Plug-in An error occurs when you do not input a value for a non-null field. Input a valid value for the field. Internal error occurred. Class=[ %1 ], Method=[ %2 ], Cause=[ %3 ]. BW-MONGODB errorrole BW_Plug-in Internal error occurs in an activity. Configuration error. [ %1 ] errorrole BW_Plug-in An error occurs when you configure the plug-in at design time. Please contact TIBCO support. Check error(s) listed in the error message and take appropriate action. BW-MONGODB Unable to get value for the global variable [ %1 ] because [ %2 ] errorrole BW_Plug-in Unable to get value for the specified global variable. Make sure that the specified global variable is defined. BW-MONGODB The global variable [ %1 ] is not defined errorrole BW_Plug-in Unable to get value for the specified global variable. Make sure that the specified global variable is defined.

107 91 Index B BucketName 25 H HTTP Receiver 72 C CollectionName 31 Connection URL 19 ContinueOnError 25, 41, 47 CR Credential 20 CR Credential Authentication 20 customer support xv D Database Command 53 E Error Codes 88 F File Query Type 30 G Get MongoDB Connection 50 I Insert Document 21 Invoke REST API 72 Is GridFS 24, 30, 46 K Kerberos Authentication 20 L Limit 31, 60 M Managing Logs 86 Map-Reduce 50 Map phase 57 Reduce phase 57 MongoDB Connection 17 Security 20 MongoDB Overview 2 MongoDB Palette 15 Multi 47

108 92 Index O OutputTarget 60 OutputType 60 U Update Document 38 Multi 41 Upsert 41 P Parse XML 74 Plain URL 17, 19 Plug-in Overview 3 W Write Concern 22, 23, 39, 45 Q Query Documents 28 Fetching Subsets of the Result Set 36 Query Type 29 R Read File 74 Read Preference 30, 54, 58 Remove Document 44 REST Dispatch and Reply 72 S Security 20 Skip 31 support, contacting xv T technical support xv TIBCO_HOME xiii