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

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  

Note:  This Connector is available from the TIBCO Scribe® Online Marketplace. See Marketplace TIBCO Scribe® Certified Connectors for more information.

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.

Note: The TrialOrganization child entity is no longer supported, but continues to display in the CreateWith Block.

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

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:

Note: If you are using TIBCO Scribe® Online as a capability of TIBCO Cloud ™ Integration, see TIBCO Scribe® Platform API Connector under the TIBCO Cloud ™ Integration help.

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.

Note: Refreshing metadata for the Connector consumes API calls.

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

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 Scribe® Online users. Depending on the entities supported, a TIBCO Scribe® Online user could alter user accounts in the target system.

  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 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:

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:

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

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.

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.

Note: The Net Change date is ignored when previewing data on the Preview tab. Filters on the Block Properties Filters tab are used to filter the data on the Preview tab.

Filtering, Match Criteria, And Lookup

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.

Connection

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

Connector

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

Error

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

History

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

InvitedUser

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

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.

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.

ManagedConnector

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

Map

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

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.

OrganizationUser

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

Solution

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

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.

Note: Connection property names are case-sensitive.

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.