TIBCO Scribe® Online Connector For TIBCO Cloud™ AuditSafe

Use the TIBCO Scribe® Online Connector For TIBCO Cloud™ AuditSafe to capture and record transactions coming from another product in TIBCO Cloud™ AuditSafe to create an audit trail.

Connector Specifications

	Supported
Agent Types
Connect on-premise	X
Connect cloud	X
Data Replication Apps
Source
Target
On Schedule Apps
Source	X
Target	X
On Event Apps
Source	X
Target	X
Flows
Integration	X
Request-Reply	X
Message

Note:

This Connector is available from the TIBCO Cloud™ Integration Marketplace. See Marketplace Connectors for more information.

Supported Entities

The TIBCO Cloud™ AuditSafe Connector supports the following entities. Click a linked entity name for additional information when using that entity in TIBCO Cloud™ Integration - Connect. For a list of additional operations by entity see Special Operations.

Standard Operations

Entity	Query	Create	Update	Delete	Upsert
Transaction	X	X

CreateWith — Container Block used with Hierarchical Data to add a parent record that may contain one or more child records. This Block collects all of the data for a single record before writing the entire record to the target. See CreateWith Block.
Add — Used for Hierarchical Data to add child records to the parent selected in a CreateWith or UpdateWith Block. See Add Block.

Special Operations

Entity	Operations
Transaction	-Add -CreateWith

Entity

Operations

Transaction

-Add

-CreateWith

Setup Considerations

Supports TIBCO Cloud™ AuditSafe.

Selecting An Agent Type For TIBCO Cloud™ AuditSafe

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To TIBCO Cloud™ AuditSafe

Note: Best practice is to create Connections with credentials that limit permissions in the target system, following the principle of least privilege. Using Administrator level credentials in a Connection provides Administrator level access to the target system for TIBCO Cloud™ Integration - Connect users. Depending on the entities supported, a TIBCO Cloud™ Integration - Connect user could alter user accounts in the target system.

Select Connections from the menu.
From the Connections page select Create to open the Create a connection dialog.
Select the Connector from the list to open the Connection dialog, and then enter the following information for this Connection:
- Name — This can be any meaningful name, up to 25 characters.
- Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
- Username — Your AuditSafe username.
- Password — Your AuditSafe password.
- Region — Select your AuditSafe region.
- Organization — Enter the name of your AuditSafe organization. This is only applicable if you belong to more than one subscription in the selected region.
- Extra Properties — Enter field names for custom fields on Transaction records to be added when using the Create operation. Field names must be separated by commas. Spaces and special characters are removed automatically when displayed in the TIBCO Cloud™ Integration - Connect user interface, but are included when the data is sent to AuditSafe. They can be used to define fields for child records. In this case, the Transaction parent and child are treated as a single record when being sent to the AuditSafe API.
  Note: Custom fields added using Extra Properties display in the CreateWith Block, but are not supported when using CreateWith. Only the Create operation supports using custom fields.
Select Test to ensure that the agent can connect to your database. Be sure to test the Connection against all agents that use this Connection. See Testing Connections.
Select OK/Save to save the Connection.

Metadata Notes

Consider the following for AuditSafe data fields and entity types.

DateTime

In AuditSafe datetime stamps are strings with the following format:

YYYY-MM-DDThh:mm:ssZ

"2018-04-24T16:07:28.019-07:00"

The datetime must include a + or - for the GMT timezone. Use the FORMAT function to format any datetime written to AuditSafe.

Example:

FORMAT("yyyy-MM-ddTHH:mm:ss.FFFZ",GETDATETIME())

Data Types

Only strings are supported.

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Relationships

Supports Hierarchical target operations, such as CreateWith and Add, to write parent/child records to AuditSafe. See Hierarchical Data and Mapping Hierarchical Data Fields for examples.

Retry Logic

If a request fails, the Connector does not retry.

AuditSafe Connector As An App Source

Consider the following when using the AuditSafe Connector as an app source.

Query

Child records display on the Query Block Properties - Include tab, but are not returned when querying AuditSafe Transactions.

Filtering

Net Change is not supported.
Filtering on the Extra Properties added in the Connection dialog is supported.
limit — Use this filter parameter to set the maximum number of records returned by the query. The default is 1000.
includePayload — Use this filter parameter to indicate whether or not to return a payload in the response results. The default is false.
event_start_timestamp and event_stop_timestamp —
- Only the equals operator is supported.
- If both fields are used in filters, the operator is ignored and all records between the two timestamps are returned.
- If only event_start_timestamp is used, all records after the selected timestamp are returned.
- If only event_stop_timestamp is used, all records before the selected timestamp are returned.
- Supported timestamp formats for these fields include both YYYY-MM-DDThh:mm:ssZ and YYYY-MM-DD.
Only the equals, is like, and is not equal to operators are supported.
AND is supported.
Note: Using AND to filter by the same field multiple times, such as audit_event=1001 AND audit_event=1002, functions like OR and returns all matching records. In this example, both 1001 and 1002 are returned.
OR is only supported when filtering by the same field multiple times, such as transaction_id=1000 OR transaction_id=1015.

Note: Using both AND and OR in a filter generates a Query exception.

AuditSafe Connector As An App Target

Consider the following when using the AuditSafe Connector as an app target.

Batch Processing

Batch processing is supported for the Create Block. See Batch Processing for more information.

Create vs CreateWith

The AuditSafe Connector provides two operations for creating Transaction records, Create and CreateWith.

Create uses the fields stored in the Extra Properties field of the AuditSafe Connection dialog to create both the parent Transaction record and the associated child records. Create supports batch processing, which sends groups of records in a single batch to the AuditSafe API. It creates multiple batches, as needed, to process the entire set of records. If you need to process a large number of records, performance is improved by using the Create operation.

CreateWith in conjunction with the Add operation builds a single parent Transaction record that contains multiple child records and sends that set of records to AuditSafe before processing the next record. If you only have a small number of records to process, this option may be simpler to use.

Note: Custom fields added using the Extra Properties field on the Connection dialog display in the CreateWith Block, but are not supported when using CreateWith. Only the Create operation supports using custom fields.

Notes On Standard Entities

Special information about standard entities appears below.

Transaction

NULL values are not supported for the following fields:

audit_event
biz_proc
event_desc
event_timestamp
event_status
transaction_id

CreateWith — The tas_event_id is a read-only field.

Troubleshooting

Review the following list of AuditSafe errors for possible solutions.

Error:

InvalidConnectionException, message: “Connection request return OAUTH error with oauthResponse.StatusCode”.

Cause: Could not obtain an access_token.

Resolution: The current access_token could be expired or the server is not responding.

Error:

InvalidConnectionException, message: “Failed to connect, please check your username and password”

Cause: The username or password is incorrect.

Resolution: Make sure your username and password are correct or reset your username and password in AuditSafe.

Error:

InvalidConnectionException, message: "Unknown organization " + organization + " supported organizations are: "+organizationList.

Cause: You have entered the wrong organization in the Connection dialog.

Resolution: Check your organization in AuditSafe and reenter it on the Connection dialog.

Error:

InvalidExecuteQueryException, message: “400 Bad Request”

Cause: Query filters are not in the correct format.

Resolution: Update the filters on the Query Block to conform to the filter rules for this Connector. If this does not resolve the error, you may need to open a Support case for further assistance.

Error:

InvalidExecuteQueryException: message: “Operator: " + <Operator>+ " Only supported when field names are the same for all fields in the filter!”

Cause: OR is only supported when each filter uses the same field name, such as transaction_id=1001 or transaction_id=1002 works, but transaction_id=1001 or event_status=”test” fails with this error.

Resolution: The AuditSafe cloud server does not support using different field names in filters with the OR operation.

Error:

InvalidExecuteQueryException, message: “All logical operators must be the same type, either AND or OR."

Cause: OR and AND are both used in a Query filter.

Resolution: Using OR and AND together in a Query filter is not supported.

Error:

InvalidExecuteQueryException, message: "Operation not supported, Operator: "+ op.ToString()

Cause: There is an unsupported operator in the filter.

Resolution: Only equals, is like, and is not equal to operators are supported. Using any other operator generates this error.

TIBCO Cloud™ Integration - Connect API Considerations

To create connections with the TIBCO Cloud™ Integration - Connect API, the AuditSafe Connector requires the following information:

Connector Name	TIBCO® AuditSafe
Connector ID	5CEA27CD-3CF1-446C-9B96-A78844BCE012

TIBCO Cloud™ Integration - Connect Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Note: Connection property names are case-sensitive.

Name	Data Type	Required	Secured	Usage
Username	String	Yes	No
Password	Password	Yes	Yes
Region	String	Yes	No	AWS region
Organization	String	No	No	Required if you belong to more than one subscription in the selected region.
ExtraPropList	String	No	No

License Agreement

The TIBCO End User License Agreement for the TIBCO Cloud™ AuditSafe Connector describes TIBCO and your legal obligations and requirements. TIBCO suggests that you read the End User License Agreement and the Voluntary Product Accessibility Template.

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.