TIBCO Scribe® Online Connector For TIBCO Scribe® Platform API

The Connector for TIBCO Scribe® Platform API uses the TIBCO Cloud™ Integration - Connect API to query, create, update, or delete TIBCO Cloud™ Integration - Connect objects, such as Organizations, Connections, apps, or flows.

Use Cases

• Setup a TIBCO Cloud™ Integration - Connect Child Organization when a new Customer is added to your Salesforce or Microsoft Dynamics 365 system.
• Synchronize users between your TIBCO Cloud™ Integration - Connect Organizations and another application, such as Salesforce, to ensure that when users are added or removed from one system they are also added or removed from the other.
• Locate new TIBCO Cloud™ Integration - Connect Users in an Organization and add those users as Contacts in another system, such as Salesforce.
• Clone apps from one Organization to another when you are managing multiple Organizations.
• Provision a new Connect cloud agent for one or more Organizations.
• Move apps from one agent to another.
• Automate testing Connections.
• Export app execution errors for reporting and analytics.
• Retrieve the status of all apps and agents across multiple TIBCO Cloud™ Integration - Connect Organizations and display them in a third-party Dashboard application or send an alert to a specific email address using another Connector.
• Save flows to a version control system or database for version management.

Connector Specifications

This Connector supports version 1.0 of the TIBCO Scribe® Platform API.

	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

Supported Entities

The TIBCO Scribe® Platform API 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
Agent	X
Connection	X	X
Connector	X
Error	X
History	X
InvitedUser	X	X
LookupTable	X	X		X
LookupTableValue	X	X	X	X
ManagedConnector	X
Map	X
Organization	X	X
OrganizationUser	X			X
Solution	X		X	X

Special Operations

• CreateWith — Container Block used with Hierarchical Data to add a parent record that contains one or more child records. This Block collects all of the data for a single record before writing the entire record to the target. For example, if the record is a SalesOrder containing five SalesOrderItems, the CreateWith Block, along with an Add Block, retrieves both the SalesOrder and the associated SalesOrderItems and writes the entire record at once to the target. See CreateWith Block.
• UpdateWith — Container Block used with hierarchical data. Use this Block to update a parent record that contains one or more child records. This Block collects all of the data for a single parent record before writing the record to the target. See UpdateWith Block.
• Add — Used for Hierarchical Data to add child records to the parent selected in the CreateWith or BuildWith Block. See Add Block.

Most special operations are executed using the Command Block.

Entity	Operations
Agent	-ProvisionCloudAgent
Connection	-TestConnection
Connector	-InstallConnector
History	-MarkAllErrors -ReprocessAllErrors
LookupTable	-CreateWith -UpdateWith
ManagedConnector	-InstallManagedConnector -RemoveManagedConnector
Map	-RunMap
Organization	-CreateWith
Solution	-CloneSolution -PrepareSolution -StartSolution -StopSolution

Setup Considerations

Requirements to use the Connector for TIBCO Scribe® Platform API are as follows:

• A TIBCO Cloud™ Integration organization with a subscription to TIBCO Cloud™ Integration - Connect.
• TIBCO Cloud™ Integration - Connect API Access enabled for the IP address or range of addresses used to connect to the API. See Security Settings.
• TIBCO Cloud™ Integration - Connect API password. TIBCO Cloud ™ User Authentication (SSO) is not supported with the API at this time. To use the API, you can establish a secondary basic authentication by selecting the Change Password option on the Security dialog. See Security Settings.
• Your Organization ID. To locate your Organization ID, query the Organization entity to return all of your Organizations. The ID is part of the model returned for each Organization.

API Usage Limits

TIBCO limits the number of calls to its API on a per minute and per calendar day basis. The Connector throttles API calls to one per second in an attempt to avoid exceeding the API limits.

If you have more than one Connection to the TIBCO Scribe® Platform API using the same credentials, the limits may be exceeded if more than one app using those Connections runs simultaneously. Exceeding these limits may result in API calls for that Organization failing with the following error: Rate Limit Exceeded . These errors continue for a period of time after the situation is resolved.

Refer to Rate Limiting in our Developer Portal for more information.

Retry Logic

For operations that may run for a long time, such as PrepareSolution or TestConnection, the Connector tries 10 times to get a success response from the API with a delay of 10 seconds between retries. If it fails, the last response is returned as a result of the associated operation Block. By returning the failure in the results of the Block, the status is available for use by other Blocks in the flow, which allows you to make a decision about how to proceed at design time. For example, by using an If/Else Block you can decide to end the flow if the result of a prior operation is a failure.

Selecting An Agent Type For The TIBCO Scribe® Platform API

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 Scribe® API

1. Select Connections from the menu.
2. From the Connections page select Create to open the Create a connection dialog.
3. 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.
   • Base URL To Scribe API — URL of the TIBCO Cloud™ Integration - Connect API. To connect to the TIBCO Cloud™ Integration - Connect Production environments, enter one of the following:
     • AWS — https://api.scribesoft.com
     • Azure — https://us1-connect-api-azure.scribesoft.com/
   • Default Organization ID — Organization ID of the TIBCO Cloud™ Integration - Connect Organization to which you want to connect. Requires API access to the selected Organization. See Security Settings. This field is optional. For additional information, see Organization ID.
   • Username — Your TIBCO Cloud™ Integration - Connect username. This is the email address you use to log into TIBCO Cloud™ Integration - Connect.
   • Password — Your TIBCO Cloud™ Integration - Connect password.
4. Select Test to ensure that the agent can connect to the TIBCO Scribe® Platform API. Be sure to test the Connection against all agents that use this Connection. See Testing Connections.
5. Select OK/Save to save the Connection.

Troubleshooting The TIBCO Scribe® API Connection

If a Connection fails, review this section for possible error messages and troubleshooting suggestions.

Unknown error occurred

The cause may be one of the following:

• The Default Organization configured in the Connection dialog does not have API access enabled. See Security Settings.
• The logged in TIBCO Cloud™ Integration - Connect User does not have access to the Default Organization configured for the Connection.

  Invalid Username or Password

• Username or Password provided on the Connection dialog do not match.

  Invalid Base URL to Scribe Online API

• The Base URL provided on the Connection dialog cannot be reached.

If all required fields are not completed, the Test button remains disabled and red validation errors are displayed for each missing field. For the TIBCO Scribe® Platform API Connection, you must complete the following fields:

• Name
• Alias
• Base URL To Scribe API
• Username
• Password

Metadata Notes

Consider the following for data fields and entity types.

DateTime

DateTime data defaults to UTC unless otherwise specified. See Solution Schedule RecurringModel Timezone in the TIBCO Developer Portal for a list of recognized timezones.

Relationships

• Hierarchical relationships, such as grandparent, parent, grandchild relationships are supported where noted for some entities. See Hierarchical Data for examples.

Organization ID

Organization ID is required as a Filter, Match, or Lookup criteria for all entities except Organization. To locate your Organization ID, query the Organization entity. The ID is returned as part of the data model for each Organization where you are a member. This ID can be specified in two ways, either by setting a Default Organization ID on the Connection dialog for the TIBCO Scribe® Platform API or by setting a Filter, Match, or Lookup criteria for the OrganizationId in an operation Block. Results differ based on the combination of settings used.

• If a Default Organization ID is specified in the Connection dialog for the TIBCO Scribe® Platform API, and no OrganizationId is specified as a Filter, Match, or Lookup criteria in an operation Block, the Connector uses the Default Organization ID specified in the Connection dialog for the TIBCO Scribe® Platform API.
• If a Default Organization ID is not specified in the Connection dialog for the TIBCO Scribe® Platform API, then OrganizationId is required as a Filter, Match, or Lookup criteria in operation Blocks, such as Query or Lookup.
• If a Default Organization ID is specified in the Connection dialog for the TIBCO Scribe® Platform API and OrganizationId is also specified as a Filter, Match, or Lookup criteria in an operation Block, the OrganizationId specified in the operation Block supersedes the ID in the Connection dialog.
• If Default Organization ID is not specified either on the Connection dialog or in the Filter, Match Criteria, or Lookup in Operation Blocks, then a Fatal Error is generated and the app stops executing.

Organization ID Specified In:
Connection Dialog Default Organization ID	Operation Block OrganizationId	ID Used By Solution
X		Connection — Default Organization ID
	X	Operation Block — OrganizationId
X	X	Operation Block — OrganizationId
		None — Generates a Fatal Error

TIBCO Scribe® Platform API Connector As An App Source

Consider the following when using the TIBCO Scribe® Platform API Connector as an app source.

Net Change

Filtering for new and updated records using the Net Change tab on the Query Block is only supported for some entities. Refer to the Notes On Standard Entities section.

When a datetime is configured on the Query block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Cloud™ Integration - Connect builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

Filtering, Match Criteria, And Lookup

• Only the AND logical operator is supported. OR is not supported
• Only the Equals comparison operator is supported.
• Mutually exclusive comparisons, such as ID = 1 AND ID = 2, generate a Fatal Error.
• Name — When filtering an entity by Name:
  • Wild cards are not supported.
  • Name filters are not case sensitive.

TIBCO Scribe® Platform API Connector As An App Target

Consider the following when using the TIBCO Scribe® Platform API Connector as an app target.

Batch Processing

Batch Processing is not supported.

Target Operations

The Command Block executes special operations for specific entities, such as CloneSolution to make a copy of a Solution in a user-specified Organization. Each operation has specific requirements. See the entities in the Notes On Standard Entities section below for specific target operation requirements. For additional information, see the API Endpoint Reference section of the TIBCO Developer Portal.

Notes On Standard Entities

Special information about standard entities appears below.

Agent

For additional information on agent endpoints and associated fields, see Agents in the TIBCO Developer Portal.

• Query — Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
• ProvisionCloudAgent — Adds a Connect cloud agent to the Organization. Only one Connect cloud agent can be provisioned per Organization.

Connection

For additional information on Connection endpoints and associated fields, see Connections in the TIBCO Developer Portal.

• Query — Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
• Create —
  • In the target Field mappings, the Name, ConnectorId, and Color fields are required. Color must be specified in hexadecimal ARGB format, such as #FF00B050.
  • Credentials required to complete and test the Connection cannot be configured using the Create Block. Log into the TIBCO Cloud™ Integration - Connect user interface and configure the credentials manually.
  • The TIBCO Scribe® Platform API does not support creating Connections for some OAuth Connectors. Refer to the Help for the specific Connector to determine if there is API support for creating Connections.
• TestConnection —
  • In the target Field mappings, the AgentId and ConnectionId fields are required.
  • This command is a combination of two API calls. The first tests the Connection and the second returns the results of the test. When using TestConnection in a Command Block, the results of both API calls are available for subsequent operations. Use these results to determine whether or not the Connection test was successful before proceeding, such as in an If/Else Block.

Connector

For additional information on Connector endpoints and associated fields, see Connectors in the TIBCO Developer Portal.

• Query —
  • Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
  • Returns only the Connectors installed for the selected Organization.
  • Due to the length of time required to complete the installation of a Connector, the list of Connectors returned may include a Connector that has not completed the installation process.
• InstallConnector —
  • Requires the ConnectorId field in the target Field mappings. To locate Connector IDs for each Connector, refer to the Help page for the specific Connector you are installing. See the Table of Contents for links to Connector Help.
  • Installs the selected Connector on all agents in the Organization. There can be a long delay when installing a Connector.

Error

For additional information on Error endpoints and associated fields, see Errors in the TIBCO Developer Portal.

• Query — Filtering by OrganizationId, SolutionId, and HistoryId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.

History

For additional information on History endpoints and associated fields, see History in the TIBCO Developer Portal.

• Query —
  • Filtering —
    • OrganizationId and SolutionId are required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
    • Use the LaterThanDate field in a filter to filter app executions by date of execution. Returns executions for the selected date and later. If not set, returns last 45 days of executions.
  • Sorting — Sort returned data by adding the following filters with the equals operator:
    • ExecutionHistoryColumnSort — Enter the name of the column to used when sorting data. Requires the SortOrder filter. Options include:
      • Start — Execution start date and time.
      • Result — Execution result. See result for a list of result types.
      • RecordsProcessed — Number of records processed.
      • RecordsFailed — Number of records failed.
    • SortOrder — Requires the ExecutionHistoryColumnSort filter. Defaults to ascending if not set. Enter the order in which records should be sorted:
      • asc — Sort in ascending order, such as 1,2,3.
      • desc — Sort in descending order, such as 3,2,1.
• MarkAllErrors — Marks all errors from an app execution for reprocessing or clears the reprocess mark from all errors associated with an app execution history. In the target Field mappings, set the formula in the Mark field as follows:
  • true — Set reprocess flag to true.
  • false — Clear reprocess flag.
• ReprocessAllErrors — Reprocesses all records with errors for a single app execution. If the original app with errors is running, this command is ignored.

InvitedUser

For additional information on InvitedUser endpoints and associated fields, see InvitedUsers in the TIBCO Developer Portal.

• Query — Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
• Create —
  • Sends an invitation via email for the associated person to join the specified Organization as a user.
  • Invited users' status is set to Pending until the invitation is either accepted or declined.
  • The invitation must be accepted for the recipient to become a user in the specified Organization.

LookupTable

For additional information on LookupTable endpoints and associated fields, see LookupTables in the TIBCO Developer Portal.

LookupTable relationships to LookupTableValue are considered hierarchical because one or more LookupTableValue records are contained within a single LookupTable record. See Hierarchical Data, Block Properties Include Tab — Hierarchical Entities.

• Query —
  • Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
  • Relationships — Hierarchical relationships are supported when querying the LookupTable entity.
• Create —
  • Requires the Name field in the target Field mappings.
  • LookupTable names must be unique for the Organization. If more than one LookupTable is created with the same name, a number is appended, such as States, States 1, States 2.
  • LookupTables and LookupTableValues cannot be created in the same operation. You must create the LookupTable first, then create the LookupTableValues.
• UpdateInsert — This operation is not supported.
• UpdateWith —
  • Supported for the LookupTable entity. See UpdateWith Block.
  • Requires the Id field for the LookupTable on the Matching Criteria tab.
  • Updates only the LookupTable name and description, not the LookupTableValues.
  Note: Using an Add Block with the UpdateWith Block to add LookupTableValues to an existing Lookup Table deletes all existing LookupTableValues before adding the new ones.
• Delete — Requires the Id field for the LookupTable on the Matching Criteria tab. If more than one match is found an error is generated.

LookupTableValue

For additional information on LookupTable endpoints and associated fields, see LookupTables in the TIBCO Developer Portal.

LookupTableValue entity is a child of the LookupTable entity.

• Query —
  • Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
  • Duplicate LookupValues are allowed by the API, however, the first item found alphabetically is returned.
• Create —
  • LookupTables and LookupTableValues cannot be created in the same operation. You must create the LookupTable first, then create the LookupTableValues.
  • Requires the LookupTableId field in the target Field mappings. If not provided, a fatal error is generated and the app stops executing.
• Update — Requires the LookupTableId and Id fields on the Matching Criteria tab. The Id field is the ID of the pair of Values being updated. If the Matching Criteria is not provided a fatal error is generated and the app stops executing.
• UpdateInsert — This operation is not supported.
• Delete — Requires the LookupTableId and Id fields on the Matching Criteria tab. The Id field is the ID of the pair of Values being deleted.

ManagedConnector

For additional information on ManagedConnector endpoints and associated fields, see ManagedConnectors and Customers in the TIBCO Developer Portal.

• Query —
  • Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
• InstallManagedConnector — Grants the selected Organization access to a private Connector.
  • Requires the ConnectorId and Id fields in the target Field mappings. The Id field is the Organization ID of the customer Organization that is being granted access to the Connector.
  • Installs the selected Connector on all agents in the Organization. There can be a long delay when installing a Connector.
• RemoveManagedConnector — Removes access to a private Connector for the selected Organization.
  • Requires the ConnectorId and Id fields in the target Field mappings. The Id field is the Organization ID of the customer Organization whose access to the Connector is being removed.
  • Removes the selected Connector from all agents in the Organization.

Map

For additional information on Map endpoints and associated fields, see Maps in the TIBCO Developer Portal.

• Query —
  • Filtering by OrganizationId and SolutionId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
  • Returns the JSON for the selected flow as a mappable field called MapJson, which allows one or more versions of the flow to be stored in a separate datastore. To import the stored flow through the TIBCO Cloud™ Integration - Connect User Interface, the JSON must be contained in an array by manually adding brackets [ ] around the contents before importing the JSON file.
• RunMap — Executes the selected flow.
  • In the target Field mappings, both the SolutionId and MapId fields are required.
  • If either the specified flow or the app containing the flow is running, this command is ignored.

Organization

For additional information on Organization endpoints and associated fields, see Organizations in the TIBCO Developer Portal.

Organization relationships are considered hierarchical because one or more Administrators, SecurityRules, and/or SolutionStatusErrors records are contained within a single Organization record. See Hierarchical Data, Block Properties Include Tab — Hierarchical Entities.

• Query —
  • Returns all Organizations for the user credentials configured on the Connection dialog.
  • When filtering by the FilterByApiAccess field, true returns only the Organizations where your IP address is configured for TIBCO Cloud™ Integration - Connect API access. Setting the filter to False returns all Organizations. See Security Settings.
  • Relationships — Hierarchical relationships are supported when querying the Organization entity.
• Create —
  • Only Child Organizations can be created, not Parent or regular Organizations.
  • Requires the ParentId and Name fields in the target Field mappings. ParentId is the Organization ID of the Parent Organization and Name is the name to assign to the new Child Organization.

OrganizationUser

For additional information on OrganizationUser endpoints and associated fields, see Users in the TIBCO Developer Portal.

• Query —
  • Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
  • Returns both active and pending users.
• Delete — Requires email address as Matching Criteria to delete a User from an Organization.

Solution

For additional information on app endpoints and associated fields, see Solutions in the TIBCO Developer Portal.

• Query — Filtering by OrganizationId is required. Organization ID can be specified either on the Filter tab in the Query Block or by including the Default Organization ID on the Connection dialog. See Organization ID.
• Filters —
  • Using Net Change to filter for new and updated records is supported for this entity using either the LastRunTime or NextRunTime field. Records are returned in ascending order.
  • When filtering apps by the Name field, the equals operator acts as a contains operator. For example, if you have apps named Event 1, Event 2, and Merge 1, and you enter "vent" as the value for the Name filter, both Event 1 and Event 2 are returned.
• Sorting — Sort returned data by adding the following filters with the equals operator:
  • SortName — Enter the name of the column to used when sorting data. Defaults to Name if not set. Requires the SortOrder filter. Options include:
    • Name — Solution name.
    • Type — Solution type. See solutionType for a list of types.
    • Status — Solution status. See status for a list of statuses.
    • LastStartTime — Date and time in UTC that the app last started running.
    • NextStartTime — For Scheduled Solutions, the date and time in UTC when the app is scheduled to run next.
  • SortOrder — Requires the SortName filter. Defaults to ascending if not set. Enter the order in which records should be sorted:
    • asc — Sort in ascending order, such as 1,2,3.
    • desc — Sort in descending order, such as 3,2,1.
  Note: Sorting cannot be used in conjunction with Net Change to filter by the LastRunTime or NextRunTime fields.
• CloneSolution — Used to copy an app from one Organization to another. Requires the following: 
  • DestinationOrganizationId — ID of the target Organization where the app is being copied.
  • DestinationAgentId — ID of the agent in the target Organization to associate with the copied app.
  • All flows in the source app must be valid.
  • New apps are incomplete until you run the PrepareSolution command against them.
    Note: Destination Organization must have the same Connection types and names, or the app must be edited manually after it is copied. If Connection types and names do not match, the PrepareSolution command fails.
• PrepareSolution —
  • This command is a combination of two API calls.
    • The first gathers all the Connections used in the app, gathers all the metadata that the app requires, and tries to compile each flow. This requires that the agent and any Connections that the app uses are up, available, and valid in the target Organization.
    • The second returns the status of the Prepare command. When using PrepareSolution in a Command Block, the results of both API calls are available for subsequent operations. Use these results to determine whether or not the app was prepared successfully, such as in an If/Else Block.
  • Requires the OrganizationId and SolutionId fields in the target Field mappings.
  • If you have configured a Default Organization ID on the Connection dialog and included a different OrganizationId on the Query Filter tab, the OrganizationId field must be mapped on the Fields tab of the Command Block, however there is no indication that it is required. If OrganizationId is not specified, the following error message is generated, but it does not provide information about the root cause.

    Error in calling Operation Command: Operation failed.

• StartSolution — Starts the selected app. This command is ignored if the app is already running.
  • Requires the OrganizationId and SolutionId fields in the target Field mappings.
• StopSolution — Stops the selected app if it is running.
  • Requires the OrganizationId and SolutionId fields in the target Field mappings.

TIBCO Cloud™ Integration - Connect API Considerations

To create Connections with the TIBCO Cloud™ Integration - Connect API, the TIBCO Scribe® API Connector requires the following information:

Connector Name	Scribe Platform API
Connector ID	DF38C2F6-4A31-4D74-8D00-4C0D96BCABEA

TIBCO Cloud™ Integration - Connect Connection Properties

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

Name	Data Type	Required	Secured	Usage
ScribeApiUrl	String	Yes	No
DefaultOrgId	String	No	No	Integer
Username	String	Yes	No
Password	String	Yes	Yes

More Information

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

Developer Portal

Sample code for this Connector along with our development methodology are available in the Sample Projects section of the TIBCO Developer Portal. See TIBCO Scribe® Platform API Connector Sample.