TIBCO Scribe® Online Connector For TIBCO Scribe® Platform API

The Connector for TIBCO Scribe® Platform API uses the TIBCO Scribe® Online API to query, create, update, or delete TIBCO Scribe® Online objects, such as Organizations, Connections, Solutions, or Maps.

Use Cases

• Setup a TIBCO Scribe® Online Child Organization when a new Customer is added to your Salesforce or Microsoft Dynamics 365 system.
• Synchronize users between your TIBCO Scribe® Online 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 Scribe® Online Users in an Organization and add those users as Contacts in another system, such as Salesforce.
• Clone Solutions from one Organization to another when you are managing multiple Organizations.
• Provision a new Cloud Agent for one or more Organizations.
• Move Solutions from one Agent to another.
• Automate testing Connections.
• Export Solution execution errors for reporting and analytics.
• Retrieve the status of all Solutions and Agents across multiple TIBCO Scribe® Online Organizations and display them in a third-party Dashboard application or send an alert to a specific email address using another Connector.
• Save Maps 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
On Premise	X
Cloud	X
Replication Services
Source
Target
Integration Services
Source	X
Target	X
Migration Services
Source	X
Target	X
Maps
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 Scribe® Online. 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:

• TIBCO Scribe® Online Organization
• TIBCO Scribe® Online API Access enabled for the IP address or range of addresses used to connect to the API. See Setting Security Options.
• Your Organization ID. To locate your Organization ID open the Organization drop-down in the banner. The ID is located under the Organization name. You can also query the Organization entity to return all of your Organizations and view the ID in the Query Preview tab.

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 Solution 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 Map, 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 Map if the result of a prior operation is a failure.

Selecting An Agent Type For The TIBCO Scribe® Platform API

Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.

Connecting To TIBCO Scribe® API

1. Select More > Connections from the menu.
2. From the Connections page select Add to open the Add a New Connection dialog.
3. Select the Connector from the drop-down list in the Connection Type field, 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 Scribe® Online API. To connect to the TIBCO Scribe® Online 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 Scribe® Online Organization to which you want to connect. Requires API access to the selected Organization. See Setting Security Options. This field is optional. For additional information, see Organization ID.
   • Username — Your TIBCO Scribe® Online username. This is the email address you use to log into TIBCO Scribe® Online.
   • Password — Your TIBCO Scribe® Online 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 Setting Security Options.
• The logged in TIBCO Scribe® Online 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 Solution 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 IS Source

Consider the following when using the TIBCO Scribe® Platform API Connector as an IS 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 Scribe® Online 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 Scribe® Online 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 IS Target

Consider the following when using the TIBCO Scribe® Platform API Connector as an IS 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 Cloud Agent to the Organization. Only one 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 Scribe® Online 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 Connections 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 Solution 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 a Solution execution for reprocessing or clears the reprocess mark from all errors associated with a Solution 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 Solution execution. If the original Solution 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 Solution 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 Solution 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 Map as a mappable field called MapJson, which allows one or more versions of the Map to be stored in a separate datastore. To import the stored Map through the TIBCO Scribe® Online 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 Map.
  • In the target Field mappings, both the SolutionId and MapId fields are required.
  • If either the specified Map or the Solution containing the Map 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 Scribe® Online API access. Setting the filter to False returns all Organizations. See Setting Security Options.
  • 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 Solution 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 Solutions by the Name field, the equals operator acts as a contains operator. For example, if you have Solutions 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 Solution last started running.
    • NextStartTime — For Scheduled Solutions, the date and time in UTC when the Solution 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 a Solution from one Organization to another. Requires the following: 
  • DestinationOrganizationId — ID of the target Organization where the Solution is being copied.
  • DestinationAgentId — ID of the Agent in the target Organization to associate with the copied Solution.
  • All Maps in the source Solution must be valid.
  • New Solutions are incomplete until you run the PrepareSolution command against them.

    Note: Destination Organization must have the same Connection types and names, or the Solution 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 Solution, gathers all the metadata that the Solution requires, and tries to compile each Map. This requires that the Agent and any Connections that the Solution 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 Solution 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 Solution. This command is ignored if the Solution is already running.
  • Requires the OrganizationId and SolutionId fields in the target Field mappings.
• StopSolution — Stops the selected Solution if it is running.
  • Requires the OrganizationId and SolutionId fields in the target Field mappings.

TIBCO Scribe® Online API Considerations

To create Connections with the TIBCO Scribe® Online API, the TIBCO Scribe® API Connector requires the following information:

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

TIBCO Scribe® Online 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.