Integrations¶
Creating an Integration will be the same steps for all Integration operations listed below. Start by clicking New > Integration in your application in Designer.
Enter the name of your MongoDB Connected System object, select the Integration Operation, then give it a Name and Description and the folder to Save In and click Create.
Each Integration Operation will be configured differently, as noted below.
Note
Unless noted otherwise, all parameters in all Integration Operations are expressionable, meaning that they can be mapped to rule inputs or otherwise derived at runtime.
READ Integration Operations¶
This section details all Integration Operations supported by the Connected System in a READ context. They can be used anywhere that Expressions are evaluated.
List Databases¶
This Integration executes the List Databases operation to list all Databases available in the Connected System instance.
The result.databases.name
property is the MongoDB Database name that can be used as any Integration Operation’s Database parameter value.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
databases |
List of Dictionary | Dictionaries represent the List Databases output data |
List Collections¶
This Integration executes the List Collections operation to list all MongoDB Collections in the given Database available to the connected user.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
UUIDs as String¶
MongoDB stores UUIDs as a special data type internally. When returned to Appian, they are sub-dictionaries with several properties. Chances are this is not as useful to you, so setting Yes here will ensure the string representation of the UUID is returned instead of the sub-dictionary.
Result Value¶
Field Name | Data Type | Description |
collections |
List of Dictionary | Dictionaries represent the List Collections output data |
database |
Text | The database used |
Collection Find¶
Performs the Find operation in the given MongoDB Collection and returns the matching MongoDB Documents. This is the standard operation for querying MongoDB Documents.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Sort JSON¶
A JSON string representing the sort order for a Collection.Find()
query. Sort specifies the order in which the query returns matching documents. Example, sorting by last name ascendingly, then first name ascendingly:
{ "lastName": 1, "firstName": 1 }
Projection JSON¶
A JSON string representing a Projection for a Collection.Find()
query. Projections limit the amount of data that MongoDB returns.
Example, returning MongoDB Documents that only contain first name, last name, and postal code, and omits the _id (which is always projected unless omitted):
{ "firstName": 1, "lastName": 1, "address.postalCode": 1, _id: 0 }
Limit¶
Sets the number of MongoDB Document results to return. Useful for mapping a!pagingInfo.batchSize
to use paging in your queries.
Skip¶
Sets the number of MongoDB Document results to skip before returning. Useful for mapping a!pagingInfo.startIndex
to use paging in your queries.
Max Processing Time¶
Specifies a cumulative time limit in milliseconds for processing operations on a Find operation. Note that this is not the complete time to perform the Integration Operation, nor the entire query on the MongoDB server, but only the time MongoDB is processing the query.
Read Preference¶
Refer to Read Preference in Common Configuration Parameters.
Read Concern¶
Refer to Read Concern in Common Configuration Parameters.
Include Record Id¶
Modifies the output of a query by adding a field recordId
to matching MongoDB Documents. Record Id is the internal key which uniquely identifies a MongoDB Document in a Collection.
Note
This is different from a MongoDB Document’s Object Id.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
documents |
List of Dictionary OR List of Text | The MongoDB Documents matched by the Filter JSON query, either as Dictionaries or JSON strings depending on the Output Type selected |
Collection Count¶
Performs the Count operation on the Collection, returning the number of MongoDB Documents that match the provided Filter JSON.
This is useful for determining how many total results match a given Filter JSON without returning the data. Using this in conjunction with Collection Find and a!pagingInfo()
allows for complete paging of your queries.
Parameters¶
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Read Preference¶
Refer to Read Preference in Common Configuration Parameters.
Read Concern¶
Refer to Read Concern in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
count |
Number (Integer) | The number of MongoDB Documents matched by the Filter JSON |
Collection Aggregate¶
Performs the Aggregate operation, taking in an Aggregation Pipeline in the form of a single Text parameter that represents an array of JSON pipeline operations.
Aggregates are MongoDB’s method of performing analytic operations on Collections, allowing for operations such as $match
and $group
. Please see the MongoDB documentation for further details.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Aggregate Pipeline Stages JSON¶
This parameter allows you to provide a collection of “stages” of an Aggregate Pipeline in the form of a single Text value that represents an array of JSON pipeline operations. For example, this JSON value represents an Aggregate Pipeline that returns the top 10 most common last names from a collection (e.g. Customers).
[
{
"$group": {
"_id": "$lastName",
"count": {
"$sum": 1
}
}
},
{
"$sort": {
"count": -1,
"_id": 1
}
},
{
"$limit": 10
}
]
Read Preference¶
Refer to Read Preference in Common Configuration Parameters.
Read Concern¶
Refer to Read Concern in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
documents |
List of Dictionary OR List of Text | The MongoDB Documents produced by the Aggregate operation, either as Dictionaries or JSON strings depending on the Output Type selected |
WRITE Integration Operations¶
This section details all Integration Operations supported by the Connected System in a WRITE context. These Integrations can only be used in the Call Integration Smart Service, in a Web API that uses a POST, PUT, or DELETE Request, or in a SAIL Save Into event.
Collection Find to JSON File¶
Performs the Find operation in the given MongoDB Collection and exports the results as JSON to an Appian Document. This is identical to the READ Collection Find operation except that a document is created from the output.
Parameters¶
Important
Only the parameters that differ from the READ version of Collection Find above are discussed here. For all others, see above.
Output JSON As a Single Array¶
Refer to Output JSON As a Single Array in Common Configuration Parameters.
Save to Folder¶
Refer to Save to Folder in Common Configuration Parameters.
Character Set¶
Refer to Character Set in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
jsonDocument |
Appian Document | The output file in Appian’s content management |
Collection Aggregate to JSON File¶
Performs the Aggregate operation in the given MongoDB Collection and exports the results as JSON to an Appian Document. This is identical to the READ Collection Aggregate operation except that a document is created from the output.
Parameters¶
Important
Only the parameters that differ from the READ version of Collection Find above are discussed here. For all others, see above.
Output JSON As a Single Array¶
Refer to Output JSON As a Single Array in Common Configuration Parameters.
Save to Folder¶
Refer to Save to Folder in Common Configuration Parameters.
Character Set¶
Refer to Character Set in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
jsonDocument |
Appian Document | The output file in Appian’s content management |
Create Collection¶
Performs the Create Collection operation, explicitly creating a new Collection in the given Database.
Note
It is possible to implicitly create a Collection using Insert One in Collection or Insert Many in Collection by specifying a Collection name that does not exist and ensuring that the Return error if Collection does not exist checkbox is not checked.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection name provided |
collectionCreated |
Boolean | Whether the Collection was created or not |
Create Index in Collection¶
Performs the Create Index operation, adding a new index in the given Collection. Indexes are critical for ensuring good performance on any operation that includes a Filter JSON value.
Parameters¶
Collection¶
Refer to Collection in Common Configuration Parameters.
Index JSON¶
The MongoDB Index Document in JSON form to instruct MongoDB how to create the new index.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
indexName |
Text | The name of the newly created Index |
Insert Many in Collection¶
Performs the Insert Many operation, creating new MongoDB Document instances in the Collection provided.
This Integration Operation allows you to select the source of the JSON to be inserted, either as a List of Text (an array of JSON documents) or by reading JSON from an Appian Document.
When used in conjunction with one of the other WRITE operations that produce Appian Document outputs (such as Collection Find to JSON File) this allows for the export and import of larger amounts of data without impacting Process Engine memory usage.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
JSON Source¶
This parameter allows you to select between passing in JSON values or alternatively reading JSON from an Appian Document.
Insert Many JSON Array¶
Note
Present only if JSON Source is “JSON String.”
The JSON array of MongoDB Documents to be inserted, in the form of: [ { ... }, { ... } ]
Source JSON File¶
Note
Present only if JSON Source is “JSON from Appian Document.”
The Appian Document that contains the MongoDB Documents in JSON form to be inserted.
JSON File Contains a Single Array¶
Note
Present only if JSON Source is “JSON from Appian Document.”
If Yes (or true
) then the file will be treated as a single JSON array of MongoDB Documents, e.g. [ { ... }, { ... } ]
If No (or false
) then the file must have one JSON object per line (delimited with newline), without trailing commas.
Skip Automatic Date Time Conversion¶
Note
Present only if JSON Source is “JSON from Appian Document.”
Refer to Skip Automatic Date Time Conversion in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
documentCount |
Number (Integer) | The count of new MongoDB Documents inserted into the Collection |
Insert One in Collection¶
Performs the Insert One operation, creating a new, singular MongoDB Document instance in the Collection provided.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Insert One JSON¶
The JSON value of the MongoDB Document to be inserted
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
document |
Dictionary OR Text | The MongoDB Document produced by the Insert One operation, either as a Dictionary or JSON string depending on the Output Type selected |
Update Many in Collection¶
Performs the Update Many operation, updating all MongoDB Document instances that match the provided Filter JSON.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Update Instructions JSON¶
This field accepts the JSON to instruct MongoDB how to update the MongoDB Documents matched by the Filter JSON, using Update Operators.
Skip Automatic Date Time Conversion¶
Refer to Skip Automatic Date Time Conversion in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
updateResult |
Dictionary OR Text | A Dictionary or JSON string (depending on the Output Type selected) that represents the Update Many results as defined in the MongoDB Documentation |
Update One in Collection¶
Performs the Update One operation, updating a singular MongoDB Document instance that match the provided Filter JSON.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Note
This should match a single MongoDB Document, e.g. by filtering on the MongoDB Document’s ID (ObjectID).
Update Instructions JSON¶
This field accepts the JSON to instruct MongoDB how to update the MongoDB Documents matched by the Filter JSON, using Update Operators.
Skip Automatic Date Time Conversion¶
Refer to Skip Automatic Date Time Conversion in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
updateResult |
Dictionary OR Text | A Dictionary or JSON string (depending on the Output Type selected) that represents the Update One results as defined in the MongoDB Documentation |
Replace One in Collection¶
Performs the Replace One operation, completely a singular MongoDB Document instance that match the provided Filter JSON with an entire new MongoDB Document.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Note
This should match a single MongoDB Document, e.g. by filtering on the MongoDB Document’s ID (ObjectID).
Replacement Mongo Document JSON¶
The JSON value of the new MongoDB Document to replace the one matched.
Skip Automatic Date Time Conversion¶
Refer to Skip Automatic Date Time Conversion in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
updateResult |
Dictionary OR Text | A Dictionary or JSON string (depending on the Output Type selected) that represents the Update One results as defined in the MongoDB Documentation |
Delete Many in Collection¶
Performs the Delete Many operation, deleting all MongoDB Document instances that match the provided Filter JSON.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Warning
It is very important that your Filter JSON matches only the subset of MongoDB Documents to be deleted. There is no “undo” functionality of this operation.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
deleteResult |
Dictionary | Contains the results of the operation with the following 2 keys and values |
.acknowledged |
Boolean | That the Delete One operation was acknowledged by MongoDB |
.deletedCount |
Number (Integer) | The number of MongoDB Documents deleted by this operation. |
Delete One in Collection¶
Performs the Delete One operation, updating a singular MongoDB Document instance that match the provided Filter JSON.
Parameters¶
Output Type¶
Refer to Output Type in Common Configuration Parameters.
Collection¶
Refer to Collection in Common Configuration Parameters.
Filter JSON¶
Refer to Filter JSON in Common Configuration Parameters.
Warning
It is very important that your Filter JSON matches only the single MongoDB Document to be deleted. There is no “undo” functionality of this operation.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
deleteResult |
Dictionary | Contains the results of the operation with the following 2 keys and values |
.acknowledged |
Boolean | That the Delete One operation was acknowledged by MongoDB |
.deletedCount |
Number (Integer) | The number of MongoDB Documents deleted by this operation (should always be 1 for Delete One). |
Drop Collection¶
Performs the Drop operation on a Collection, deleting the Collection and any MongoDB Documents found within.
Warning
This operation can be very destructive if not used with great caution. There is no “undo” functionality of this operation.
Parameters¶
Collection¶
Refer to Collection in Common Configuration Parameters.
Result Value¶
Field Name | Data Type | Description |
database |
Text | The database used |
collection |
Text | The collection used |
collectionDropped |
Boolean | Whether the Collection was successfully dropped |
Common Configuration Parameters¶
This section describes the collection of Parameters that are shared among multiple Integration Operations.
Output Type¶
This parameter allows you to select how the Integration Operation returns the data, either as Appian Dictionaries or as a List of Text containing the JSON representations of the MongoDB Documents. See Special Considerations for how ObjectIds are transformed when being output as Dictionaries.
When selecting the List of JSON Strings, the JSON output comes directly from the MongoDB Java Driver, which represents the data in its “purest” form.
Database¶
This parameter tells the Integration Operation which MongoDB Database to perform the operation on. The drop-down is automatically populated with the available Databases in your Connected System, using the same method as List Databases above.
Below the drop-down is a checkbox which if checked will ensure that the Database exists before performing the Operation. MongoDB is very forgiving and will allow many API methods to be performed on non-existent Databases, returning null or an empty set. Checking this box will ensure that the database exists, to help avoid entering the wrong database name.
Collection¶
This parameter tells the Integration Operation which MongoDB Collection to perform the operation on. The drop-down is automatically populated with the available Collections in the given Database in your Connected System, using the same method as List Collections above.
Below the drop-down is a checkbox which if checked will ensure that the Collection exists before performing the Operation. MongoDB is very forgiving and will allow many API methods to be performed on non-existent Collections, returning null or an empty set. Checking this box will ensure that the Collection exists, to help avoid entering the wrong Collection name.
Note
For WRITE operations (e.g. Insert One in Collection), if the checkbox is unchecked and the Collection does not exist, MongoDB will create a new Collection with the given name to perform the write into. This can be an unintended action, but it can also be very useful when performing certain business functions, such as reading back the results of a Collection Aggregate and writing them to a new Collection in one nested operation.
Filter JSON¶
This parameter represents a MongoDB Query Document in JSON form. This is the query language that MongoDB uses, similar to how RDBMS platforms use SQL. When present, the value provided here will be used to match MongoDB Documents in the given Collection.
For READ operations such as Find, this will determine which MongoDB Documents are returned.
For WRITE operations such as Update, this will determine which MongoDB Documents are modified, so it is critical your Filter JSON matches only those to be modified. It is therefore a good idea to test your Filter JSON values for WRITE operations before performing them (e.g. by performing a Find first and validating that only the documents to be updated are returned).
This JSON string value can be hard-coded, constructed via Expressions or Expression Rules, or constructed using the JSON Query Expression Functions as shown:
Output JSON As a Single Array¶
This will join the results as a JSON array such as: [ { ... }, { ... } ]
, allowing easier import using Insert Many in Collection or other MongoDB tools. Selecting No (or false) will write one MongoDB Document per line.
Save to Folder¶
The Appian Folder where the new Document will be created. This is a standard Appian folder picker.
Filename¶
The complete name of the output file, including any extension you would like (most commonly .json)
Skip Automatic Date Time Conversion¶
This plugin will attempt to detect Dates and Times and convert them to MongoDB timestamps. Selecting Yes (or true) here will skip this and instead insert these values as Strings.
Character Set¶
The character set that the text file should use. Valid values are:
Value | Description |
ISO-8859-1 |
ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1 |
UTF-8 |
Eight-bit UCS Transformation Format |
UTF-16LE |
Sixteen-bit UCS Transformation Format, little-endian byte order |
UTF-16 |
Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark |
UTF-16BE |
Sixteen-bit UCS Transformation Format, big-endian byte order |
US-ASCII |
Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set |
Collation¶
Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. This parameter section allows you to individually configure a Collation Document, or you can define one by building an Appian Dictionary (and not a JSON string) in the form of:
Read Preference¶
Read Preference describes how MongoDB clients route read operations to the members of a replica set.
Read Concern¶
Read Concern allows you to control the consistency and isolation properties of the data read from replica sets and replica set shards.