Create a Connection
Connections
A Connection is the configuration, including the login and other parameters, needed to connect to any datastore used by TIBCO Scribe®. For example, the Salesforce Connector connects to the Salesforce API to read and write data. The credentials that permit that Connector to communicate with the Salesforce API are stored in a Connection. Every Connection is named to allow you to organize and track your TIBCO Scribe® Connections. Each Connector has different Connection requirements. Review the Help for the Connector you plan to use. See Connections in the TIBCO Scribe® Help.
Before using the TIBCO Scribe® API to create, update, or delete Connections, review the following topics:
- Connection Properties
- Create And Test A Connection
- Create Or Modify An OAuth Connection
- Manually Load Metadata
Endpoints— Use the links in the Endpoints section below to access the TIBCO Scribe® Swagger page and try out the API against your Organization.
Fields For Connections Endpoints — Review the field definition table below the list of Endpoints for detailed field level information.
Considerations
In some cases there are special considerations or use cases for specific endpoints that you should know about before you use the endpoint.
POST /v1/orgs/{orgId}/connections
- Provide all key-value pair information in the properties section of the model. Otherwise, these properties are set to blank values. To find out which properties are used by a Connector, see the help for that Connector under Connections in the TIBCO Scribe® Help. See properties in the Fields For Connections Endpoints table for additional information.
- When creating a new Connection, the Connection Alias is derived by TIBCO Scribe® from the Connection Name and cannot be modified. It can be modified later using a PUT method.
PUT /v1/orgs/{orgId}/connections/{connectionId}
- Protected properties, such as passwords, can be omitted from this call and still retain their original value. Non-protected properties omitted from the call are set to blank values. See properties in the Fields For Connections Endpoints table for additional information.
GET /v1/orgs/{orgId}/connections/{connectionId}/actions
- If metadata needs to be loaded by the Agent, this function starts loading the metadata, and returns a 404 continuously until loading is complete. Add a delay and submit the call repeatedly until a list of Actions is successfully returned.
GET /v1/orgs/{orgId}/connections/{connectionId}/entities
- If metadata needs to be loaded by the Agent, this function starts loading the metadata, and returns a 404 continuously until loading is complete. Add a delay and submit the call repeatedly until a list of Entities is successfully returned.
- If a large number of entities need to be loaded, and you are using the offset to retrieve them in batches, the second batch may try to load before the first batch is finished preventing some entities from loading.
Workaround: Use GET /v1/orgs/{orgId}/connections/{connectionId}/supportedactions instead. The entities are loaded in addition to the actions.
GET /v1/orgs/{orgId}/connections/{connectionId}/entities/{entityIdOrName}/fields
- If metadata needs to be loaded by the Agent, this function starts loading the metadata, and returns a 404 continuously until loading is complete. Add a delay and submit the call repeatedly until a list of Fields is successfully returned.
GET /v1/orgs/{orgId}/connections/{connectionId}/entitynames
- If metadata needs to be loaded by the Agent, this function starts loading the metadata, and returns a 404 continuously until loading is complete. Add a delay and submit the call repeatedly until a list of Entity names is successfully returned.
GET /v1/orgs/{orgId}/connections/{connectionId}/supportedactions
- If metadata needs to be loaded by the Agent, this function starts loading the metadata, and returns a 404 continuously until loading is complete. Add a delay and submit the call repeatedly until a list of supported Actions is successfully returned.
POST /v1/orgs/{orgId}/connections/test
- Test a Connection without saving the Connection model.
Endpoints
Return a list of Connections for an Agent
Delete a Connection
Return information about a Connection
Modify a Connection
Return a list of Actions for a Connection
Return a list of Entities for a Connection
Return information about an Entity
Return a list of Fields for an Entity
Return a list of Relationships for an Entity
Return a list of Entity names for a Connection
Return latest metadata requests
Reset the metadata for a Connection
Return a list of supported Actions for a Connection
Test a Connection
Test Connection Properties
Return the status of a Connection test command
Fields For Connections Endpoints
The list of fields defined in this table is comprehensive across all Connections endpoints. See Endpoints for a list of Connections endpoints with links to the associated Swagger page.
|
Name |
Description |
Endpoints |
|---|---|---|
|
Parameters |
||
|
agentId query string |
Use this ID to limit the list of data based on whether the selected Agent has that Connection installed. For example, if the Agent is a Cloud Agent, then Dynamics GP Connection information is not returned because the Connector For Dynamics GP does not support the Cloud Agent. If loading metadata, use this ID to indicate which Agent should load metadata. If not designated, loading metadata fails if this set of metadata has never been loaded. If testing a Connection, use this ID to indicate which Agent should attempt to communicate with the datastore. Required when testing Connections. |
|
|
commandId path string |
ID returned when testing a Connection using the POST /v1/orgs/{orgId}/connections/{connectionId}/test or the POST /v1/orgs/{orgId}/connections/test endpoints. |
|
|
connectionId path string |
GUID/UUID of the configured Connection. Required |
|
|
connectionModel body schema |
Model of a single Connection including all Connection properties. Used to create and test a Connection in a single call. |
|
|
entityIdOrName query string |
ID or name of the Entity to be returned. Required |
|
|
expand query boolean |
Controls whether or not to return associated Objects. Default is true. Depending on the endpoint selected, options include:
|
|
|
limit query integer |
Maximum number of Objects to return. Default value is 100. Objects include:
See Reading Resources for more information on offset and limit parameters. |
|
|
mapType query string |
Filters data by Solution type and Map type. Types include:
Refer to Connector documents in TIBCO Scribe® Help to see which Map types are supported. Note: The IntegrationServicesBasicMap and IntegrationServicesSysControllerMap Map types are no longer supported. |
|
|
model body schema |
Model for a Connection. Required fields include: Name, ConnectorId, and Color in hexadecimal ARGB format. |
|
|
name query string |
User-specified name for the Connection. |
|
|
nestedPropertyRelations query integer |
Number of Relationship levels to return. Maximum value is 10. Default value is 0. Applies only to property type relationships. |
|
|
offset query integer |
Number of Objects to skip before returning results. Default value is 0. Objects include:
See Reading Resources for more information on offset and limit parameters. |
|
|
orgId path integer |
Unique ID for each Organization. Required |
All |
|
Response |
||
|
action response string |
Action executed if the selected operation is used. For example, an operation called Insert would execute the Create action. See knownAction for a list of actions and definitions. |
|
|
actions response array |
Array of Actions and associated properties supported for an Entity. |
|
|
agentId response string |
GUID/UUID of the Agent that made the metatdata request. |
|
|
alias response string |
Name for the Connection that has no special characters or spaces and is compatible with TIBCO Scribe® formulas. Used by TIBCO Scribe® in Maps to track the operation results associated with a selected Connection in the Formula Editor. |
|
|
blockType response string |
Block Type associated with the Action. See Working With Blocks in the TIBCO Scribe® Help. Types include:
|
|
|
color response string |
Color, in hexadecimal ARGB format, used for display Blocks in Maps using this Connection. Since Maps can have multiple Connections, Block colors provide at-a-glance cues for the Connection associated with the selected Action, such as Create or Delete. Required. Note: This value only controls the Block color in the original TIBCO Scribe® Silverlight user interface. It has no effect on the new TIBCO Scribe® UI. |
|
|
connectionId response string |
GUID/UUID of the Connection. |
|
|
connectorId response string |
GUID/UUID of the Connector associated with this Connection. This ID can also be found in the TIBCO Scribe® Help in the documentation for the specific Connector. See Connections in the TIBCO Scribe® Help for a complete list. |
|
|
connectorType response string |
Displays the name of the Connector, such as Eloqua, Microsoft SQL Server, or Microsoft Dynamics GP. See Connections in the TIBCO Scribe® Help for a complete list. |
|
|
creationDate response string |
Date and time in UTC time that the Object was created. Objects include:
|
|
|
createDateTime response string |
Date and time in UTC time that the Connection was created. |
|
|
description response string |
Description of the Entity, Field, or Relationship. This information is returned from the datastore when metadata is loaded. |
|
|
endDate response string |
Date and time in UTC that the metadata request was completed. |
|
|
errorMessage response string |
Error message returned by the Connector when a metadata request fails: |
|
|
fullName response string |
Unique value used to reference this Object. Objects include:
Value cannot be NULL. Must contain only alphanumeric characters or underscore. IMPORTANT – When using the API, always reference entities, fields, and relationships by their fullName, and not the name or originalName. The fullName is a version of the name that has all special characters removed making it compatible with TIBCO Scribe® formulas and Maps. |
|
|
id response string |
GUID/UUID of the configured Object. Objects include:
|
|
|
isHidden response boolean |
Indicates whether the Entity is hidden or visible. When set to true this Entity is considered to be of limited value to the user because it is a system or internal Entity that is hidden from the user. |
|
|
isPrimaryKey response boolean |
Indicates whether this Field is a primary key and may be required when updating data in the datastore. |
|
|
response string |
Action performed on the datastore when this Action is used in a Map. Actions include:
See KnownAction Enumerations in the TIBCO Scribe® Connector Toolkit Help |
|
|
lastModificationDate response string |
Date and time in UTC time that the Object was last modified. Objects include:
|
|
|
lastModificationDateTime response string |
Date and time in UTC time that the Connection was last modified. |
|
|
maxOccurs response integer |
Constrains the number of times the specified field can appear in the Entity. Value of 0 = 1. Not currently used, for future support of hierarchical data. |
|
|
minOccurs response integer |
Constrains the number of times the specified field can appear in the Entity. Value of 0 = 1. Not currently used, for future support of hierarchical data. |
|
|
modificationBy response string |
ID of the Agent that modified the Object. Objects include:
|
|
|
name response string |
Name of the Object. Objects include:
Value cannot be NULL. IMPORTANT – When using the API, always reference entities, fields, and relationships by their fullName, and not the name or originalName. The fullName is a version of the name that has all special characters removed making it compatible with TIBCO Scribe® formulas and Maps. |
|
|
nullable response boolean |
Indicates whether a Field in an Entity accepts NULL values. Not currently used. |
|
|
objectDefinitionId response string |
GUID/UUID of the entity being requested. |
|
|
objectName response string |
Name of the Entity returned in the metatdata request. |
|
|
ordinal response integer |
Controls the display order of the fields when they are not sorted. Columns in the User Interface allow you to sort A to Z or Z to A. Note: This has not yet been implemented. |
|
|
operationName response string |
Name of the Operation or Action that can be executed, such as Create or Delete. Displays on the Operation Block in the TIBCO Scribe® User Interface. |
|
|
originalName response string |
Original name of the entity. In some cases, TIBCO Scribe® renames entities, fields, and relationships to remove special characters that are not compatible with TIBCO Scribe® formulas. Always refer to these objects by the fullName instead. |
|
|
response string |
A temporary ID for a parent object generated each time this endpoint is called and used to group entities and relationships. Used with uniqueId. |
|
|
path response string |
Fully qualified name for the related entity used for formulas. Format is: EntityFullName.RelatedEntityFullName |
|
|
presentationType response string |
Field's data type, such as string or GUID, for displaying the value in the field. This field is not used by TIBCO Scribe®. |
|
|
response string |
Property array containing key value pairs. Each key contains the name of a Connection parameter. The associated value contains the value for the Connection parameter. For example, for the Eloqua Connection you have a key named Company and its corresponding value contains the company name as defined in Eloqua. Note: When creating a new Connection, you must provide a key value pair for each Connection property. Otherwise, the properties are set to blank values. Note: When updating a Connection, protected properties, such as passwords, can be omitted and still retain their original value. Non-protected properties omitted during an update are set to blank values. Note: Connection properties are encrypted. See Connection Properties for additional information. |
|
|
propertyType response string |
Field's data type, such as string or double. |
|
|
response string |
Full name of the Related Entity. For example, if the selected Entity is Contact, the name of the Related Entity could be Address. See thisEntityFullName. |
|
|
response string |
Relationship fields of the Related Entity. See thisProperties. |
|
|
response string |
Types of relationships this Entity has to other Entities. Types include:
|
|
|
reply response string |
Status of a Connection test, such as SUCCESS. |
|
|
replyData response array |
Key value pairs containing the names and encrypted values for the fields on the Connection dialog. |
|
|
requiredInActionInput response boolean |
Controls the display of required fields in the TIBCO Scribe® User Interface. Should be false for fields, such as an ID fields, that are listed as “required” or NOT Nullable by the Connector's API, but are generated by the Connector's API on insert. |
|
|
size response integer |
Field length. |
|
|
startDate response string |
Date and time in UTC that the metadata request was sent. |
|
|
state response string |
Status of the metadata request. Statuses include:
|
|
|
status response string |
Status of the Connection test. |
|
|
supportsBulk response boolean |
Indicates whether the Action supports Batch processing. Instead of sending records one at a time, the Agent creates a batch of multiple records and sends the batch to the API of the target datastore in one call. This reduces API calls and increases performance. The target datastore must support bulk or Batch processing. See Batch Processing in the TIBCO Scribe® Help. |
|
|
supportsConstraints response boolean |
Indicates whether or not filters can be used. Applies only to Query actions.
|
|
|
supportsInput response boolean |
Indicates whether or not field mappings can be used. Typically this is set to false for Query and Delete actions, and true for everything else.
|
|
|
supportsLookupConditions response boolean |
Indicates whether the action supports criteria for a Lookup Operation, such as checking a datastore to determine if a record with a matching ID exists. See Lookup Block in the TIBCO Scribe® Help. |
|
|
supportsMultipleRecordOperations response boolean |
This field is not used. |
|
|
supportsRelations response boolean |
Indicates whether the Action supports parent/child relationships. Parent/child record relationships allow you to associate a single master record with a number of related records. For example, you can associate a Sales Order or parent record with multiple Sales Order Items or child records. |
|
|
supportsSequences response boolean |
This field is not used. |
|
|
tenantId response string |
GUID/UUID of the Organization that made the metatdata request. |
|
|
response string |
Full name of the selected Entity, such as Contact which could have a Related Entity of Address. See relatedEntityFullName. |
|
|
response string |
Relationship fields of the Related Entity. See relatedProperties. |
|
|
response string |
A temporary ID for a related entity generated each time this endpoint is called and used to group entities and relationships. Used with parentId. |
|
|
usedInLookupCondition response boolean |
Used to filter the list of fields that display as possible Match Criteria in an operation. |
|
|
usedInActionOutput response boolean |
This field is not used. |
|
|
usedInActionInput response boolean |
Controls the display of read only fields in the User Interface. |
|
|
usedInQueryConstraint response boolean |
Used to filter the list of source fields available for use as filters for Query or Fetch. |
|
|
usedInQuerySelect response boolean |
Used to filter the list of source fields in the Formula Editor and mapping user interface. |
|
|
usedInQuerySequence response boolean |
This field is not used. |
|
|
usedInSolutions response string |
List of Solutions configured to use this Connection. A Connection cannot be deleted if it is configured in a Solution. |
|
See