Upgrade and return a submitted Map
Maps
A Map is a set of instructions needed to integrate your data. In the TIBCO Scribe® User Interface, Maps contain a series of operation Blocks that provide a visual representation of the instructions. Sets of one or more TIBCO Scribe® Maps are used in Integration Services (IS) and Migration Services (MS) Solutions to retrieve and manipulate data. Replication Services (RS) Solutions do not use Maps because they simply copy data from one data source to another with no filtering or other data manipulation. Not all Solution types support all Map types.
Use the Maps endpoints to view, update, create, delete, run, enable/disable, and lock/unlock Maps, or export and import Maps. See the example below of a Map in TIBCO Scribe® user interface and review Maps, Managing Maps, and Exporting And Importing Maps in the TIBCO Scribe® Help for additional information.
Maps support a maximum of 250 Blocks.
Other endpoints associated with Maps include:
- Solutions — Solutions are a collection of Maps that run sequentially to integrate or migrate data. Use the Solutions endpoints to view, create, modify, delete, schedule, or start and stop Solutions. See Solutions in the TIBCO Scribe® Help.
Before using the TIBCO Scribe® API to create, update, or delete Maps or Solutions, review the following topics:
- Solution MapLinks
- Copy Or Clone A Solution To Another Organization
- Copy Or Clone A Solution Using Shared Resources
- Create Or Modify A Solution Or Map
- Manually Load Metadata
- Generate An OAS Document For Request/Reply Maps
- Blocks
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 Maps 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.
Solutions Using Shared Resources
If you copy or clone a Solution with the byReference parameter enabled, the source and target Solutions share resources, such as Maps. Some API methods for Maps are not supported for these types of Solutions. See Copy Or Clone A Solution Using Shared Resources for considerations related to Solutions with shared resources.
GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/export/{exportId}
- Use the export ID returned by the GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/export endpoint to retrieve a Map export.
GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/nativequerytest
- Returns a 404 continuously until the test is complete. Add a delay and submit the call repeatedly until test results are successfully returned.
GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery/{previewId}
- Returns a 404 continuously until Query Preview results are available. Add a delay and submit the call repeatedly until Preview results are successfully returned.
GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/relationships
- Returns only the relationships selected in the Map, not all possible relationships for the entities in the Map. To return all relationships for an entity, use GET /v1/orgs/{orgId}/connections/{connectionId}/entities/{entityIdOrName}/relationships under the Connections endpoints.
GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/revisions
- Returns all revisions of the specified Map sorted in descending order by revision number. The latest revision is returned first.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/advanced
- When creating a new Map, the lastRunDate value used for retrieving only new and changed records is saved as null instead of keeping the modified date.
POST /v1/orgs/{orgId}/solution/{solutionId}/maps/advanced/upgrade
- Use this endpoint to submit and upgrade a Map model without saving it. If you attempt to use Maps endpoints for Validate, Rename Block, or Preview Query and you have submitted a Map model that is version 2.0 or older, you must upgrade the Map model before submitting it to any of these endpoints.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/export
- When exporting Maps you can use a comma delimited list of Map IDs to export multiple Maps. The most recent revision of each Map is exported. To export a specific revision of a Map, enter only one mapID in the mapIds field and the number of the revision to export in the revision field. If you enter multiple mapIds and a revision number, the API generates an error and the export file is not created.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/import
- When a Map is imported, the revision comment Map Imported is automatically added to that revision of the Map along with a revision number, date, and user name of the user who imported the Map.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/clone
- When a Map is copied, the Map status of the new Map is set to Disabled and the Map name is set to Copy of <original Map Name> 1. Use PUT /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/enable to enable the Map and PUT /v1/orgs/{orgId}/solutions/{solutionId}/maps/advanced/{mapId} to modify the Map name.
- The most recent revision of the original Map is used.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery
- Returns the results of a Query preview or Fetch preview. If model is provided, mapId is ignored. If model is blank, mapId is used to retrieve the model for the query. See Block Properties Preview Tab in the TIBCO Scribe® Help.
- Returns a previewId. Use this ID with the GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery/{previewId} endpoint to retrieve the Query preview results.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/revert
- A Map locked by another user cannot be reverted to a prior revision.
- A reverted Map is incomplete until it is opened, validated, and saved.
- When a Map is reverted to a prior revision, the lastRunDate value used for retrieving only new and changed records does not return to the value associated with the prior revision. It remains at the value stored the last time any revision of the Map was executed.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/run
- This command is ignored if either the specified Map or the Solution containing the Map is running.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/validate
- This method causes all of the Map’s metadata to be loaded automatically.
- Returns a validation ID. Use this ID with the GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{validationId}/validationresults endpoint to retrieve the results of the validation. See value in the Fields table.
POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/validateformula
- When validating a Formula in a Map, if you provide the mapId of the Map containing the Formula, the validation fails.
Workaround: First validate the Map containing the Formula using the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/validate call. Use the validateId value returned from that call as the mapId value for the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/validateformula call.
- When validating a Formula in a Map, if you do not pass a value for the formula property a 400 Bad Request response code is returned instead of a 200 OK response code.
DELETE /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}
- Deleting an Event Message Map does not remove the associated Endpoint URL. If you create a Map with the same name, the Message Endpoint for that original Map displays on the Message Endpoints dialog.
Endpoints
Copy a Map within a Solution
Return a Map link
Return a list of Maps
Return information about a Map
Delete a Map
Modify Block type
Modify Map Enabled/Disabled state
Return information about an Event Map
Modify Map Locked/Unlocked state
Return the results of a Native Query Block test
Test Native Query Block properties
Run Query preview
Return Query preview results
Return a list of Relationships for a Map
Modify Block name
Revert a Map to a prior version
Return a list of revisions for a Map
Run a single Map
Return the status of the Run Map Now command
Validate a Formula in a Map
Return Map validation results
Create an Advanced Map
Modify an Advanced Map
Export Maps from a Solution
Return exported Maps
Import Maps into a Solution
Fields For Maps Endpoints
The list of fields defined in this table is comprehensive across all Maps endpoints. See Endpoints for a list of Maps endpoints with links to the associated Swagger page.
|
Name |
Description |
Endpoints |
|---|---|---|
|
Parameters |
||
|
query string |
List of possible actions used to modify the block type of an existing operation Block configured in a Map. The action is used in conjunction with the operationName to derive the new blockType. Actions and operationNames vary by Connection. To determine the appropriate combination of action and operationName, use the GET /v1/orgs/{orgId}/connections/{connectionId}/supportedactions endpoint for the Connection associated with the Block you are attempting to modify. See Connections. Actions include:
See Change Block Operation Type in the TIBCO Scribe® Help. |
|
|
agentId query string |
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. |
|
|
blockId query string |
GUID/UUID of the Block you are retrieving. Required When querying preview records for a Fetch Block with the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery endpoint, this field must contain the Block ID of the Fetch Block. If it is left blank, preview records for the Query Block are returned. When returning relationships, with the GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/relationships endpoint, include the Block ID for the specific Block configured with the relationships you are requesting. If this field is blank, selected relationships configured in the Query Block are returned by default. |
|
|
commandId path string |
ID returned by the Run Single Map command, POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/run. The ID of the execution of the Map is used to retrieve the status of that Map execution. Required |
|
|
comment query string |
Comment associated with a Map revision. Each time a Map is saved the revision number is incremented and an associated comment can be added. |
|
|
enableState query boolean |
Sets the Enabled/Disabled state of the Map. Default is true. See Managing Maps in the TIBCO Scribe® Help. Disabling a Map prevents the Map from running when the Solution where the Map is contained is executed.
|
|
|
exportId path integer |
ID of the export request for Maps exported from a Solution. This ID is generated by the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/export when you use it to export all Maps from a Solution and is used to retrieve the exported Maps. Required This ID can only be used once to retrieve exported Maps. |
|
|
filterByBlockId query string |
Returns errors for a single specific Block when retrieving Map validation results. |
|
|
importedMapOrder query boolean |
Controls the order in which Maps are organized in a Solution when they are imported. If a Map has the same name as an existing Map, the Map in the Solution is overwritten by the imported Map. Maps can be appended to the end of the list of existing Maps in the Solution by setting this field to true. Maps can be merged into the list of existing Maps by setting this field to false. Default is true.
|
|
|
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. |
|
|
lockMap query boolean |
Determines the locked state of the Map when it is returned. See Locking And Unlocking Maps in the TIBCO Scribe® Help. Locking a Map prevents another user from editing it and possibly overwriting changes.
|
|
|
lockState query boolean |
Sets the locked state of the Map. Default is true. See Locking And Unlocking Maps in the TIBCO Scribe® Help. Locking a Map prevents another user from editing it and possibly overwriting changes.
|
|
|
mapId path integer |
GUID/UUID of the Map you are retrieving. Required |
|
|
query string |
Comma separated list of mapIds of the Maps selected for export. If blank, all Maps in the Solution are exported. The most recent revision of each Map is exported. To export a specific revision, enter only one mapId and specify a revision number in the revision field. |
|
|
model body model |
Model for the Map, Formula, or Native Query. |
|
|
models body model |
One or more Map models to be imported. |
|
|
name query string |
Filter for a single Map using the name of the Map you want to retrieve. |
|
|
nativeQueryBlockID query string |
GUID / UUID of the test results for a Native Query Block. |
|
|
query string |
When reassigning Connections in a Map, you must provide the ID of the original or old Connection and the ID of the new or replacement Connection. Requires the oldConnectionId field. Enter the ID of the new replacement Connection. |
|
|
newName query string |
When renaming a Block in a Map, you must provide the new name for the Block. Required |
|
|
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. |
|
|
query string |
When reassigning Connections in a Map, you must provide the ID of the original or old Connection and the ID of the new or replacement Connection. Requires the newConnectionId field. Enter the ID of the Connection to be reassigned. |
|
|
query string |
Name of the operation used to modify the block type of an existing operation Block configured in a Map. The operationName is used in conjunction with the action to derive the new blockType. Actions and operationNames vary by Connection. To determine the appropriate combination of action and operationName, use the GET /v1/orgs/{orgId}/connections/{connectionId}/supportedactions endpoint for the Connection associated with the Block you are attempting to modify. See Connections. Only the following types of operation Blocks can be changed:
See Change Block Operation Type in the TIBCO Scribe® Help. |
|
|
orgId path integer |
Unique ID for each Organization. Required |
All |
|
prepareMap query boolean |
Runs Map prepare for the Map being updated. This process compiles the Map to allow it to be run. Default is false.
|
|
|
previewId path string |
GUID/UUID of the query preview returned by the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery method. Required |
|
|
query integer |
Revision number of the Map. Each time a Map is saved a new revision of the Map is created and the revision number is incremented. Allows users to go back to a prior revision of a Map, determine when a revision took place, and who modified the Map. To export a specific revision of a Map, specify a single mapId in the mapIds field and a single revision number in the revision field. |
|
|
solutionId path string |
GUID/UUID of the Solution containing the Map. Required |
|
|
unLockMap query boolean |
Sets the locked state of the Map. Default is true. See Locking And Unlocking Maps in the TIBCO Scribe® Help. Locking a Map prevents another user from editing it and possibly overwriting changes.
|
|
|
updateBlockConnectionOnly query boolean |
When reassigning a Connection, determines whether or not to remove the old Connection from the Map based on the value in the oldConnectionId field.
|
|
|
validationId query integer |
ID returned from a Map validation when the POST /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/validate method is used. Enter either the Map validation ID or the Map ID. |
|
|
validateMap query boolean |
Runs Map validation for the Map being updated. Default is false.
|
|
|
Response |
||
|
blockId response string |
GUID/UUID of the Block in the Map that contains errors. Returned in Map validation and Formula validation results. |
|
|
blocks response array |
Array of one or more Blocks and associated properties in a Map. See Blocks for a table of Block properties and definitions. |
|
|
columnMappings response array |
Array of one or more data columns defined for the data for an Event Request/Reply Map.
|
|
|
comment response string |
Comment associated with a specific revision of a Map. Comments are entered on the Map model when the Map is saved. Depending on the actions taken, some Comments are generated automatically by TIBCO Scribe®, including:
|
|
|
connectionAlias response string |
Name for the target Connection used by TIBCO Scribe® in Maps to track the entities associated with a selected Connection in the Formula Editor. |
|
|
connectionId response string |
GUID/UUID of the target Connection in the Map. |
|
|
connectionName response string |
Name of the target Connection in the Map. This name is user-specified when the Connection is created. |
|
|
connectionType response string |
Displays the name of the Connector for the target Connection, such as Eloqua, Microsoft SQL Server, or Microsoft Dynamics GP. See Connections in the TIBCO Scribe® Help for a complete list. |
|
|
createdBy response string |
User that created this Map revision. |
|
|
creationDate response string |
Date and time in UTC time that the Object was created. Objects include:
|
|
|
description response string |
Description of the one of the following:
|
|
|
enabled response boolean |
Indicates whether the Map is enabled or disabled.
|
|
|
endpointId response integer |
Applies only to Message Maps. Each Message Map has a unique Endpoint URL. Each Endpoint URL has a unique ID. |
|
|
entityName response string |
Name of the entity being sent in the event message. Applies only to Message Maps. |
|
|
error response string |
Error generated by a failed Query preview or Native Query Block test. |
|
|
eventURL response string |
Endpoint URL for an Event Map. Each Map in an Event Solution has its own unique Endpoint URL. Properly formatted web calls to that URL cause the Map to run. The Endpoint URL is generated by TIBCO Scribe® the first time the Map is saved. See Defining An Event Message Map or Defining An Event Request/Reply Map in the TIBCO Scribe® Help. |
|
|
exportId response integer |
ID of the export request for Maps exported from a Solution. Use this ID with a GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/export/{exportId} command to retrieve the exported Maps. This ID can only be used once to retrieve exported Maps. |
|
|
fields response array |
Array of Field Models for the entity generated by a Native Query test. |
|
|
fullName response string |
Unique value used to reference this Relationship. 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. |
|
|
response integer/string |
GUID/UUID of the Object being returned. Objects include:
|
|
|
index response integer |
Order of the Map in the Solution. The first Map has an index of 0, the second has an index of 1, subsequent Maps continue to increment by 1. Maps are run in the order they appear in the Solution starting with 0. |
|
|
lastModificationDate response string |
Date and time in UTC time that the Object was last modified. Objects include:
|
|
|
lastModified response string |
Date and time in UTC time that the Map was last changed. |
|
|
response string |
Date and time in UTC time that the Map was last executed. This date is used by the Net Change feature to filter for new and updated records by comparing this date to a user specified date field in the entity being queried. The name of the date field is stored in the netChangeFieldName field and is used in conjunction with the enabled/disabled setting in the netChange field. |
|
|
lockedBy response string |
User name of the TIBCO Scribe® user who has locked the Map. See Locking And Unlocking Maps in the TIBCO Scribe® Help. |
|
|
lockDate response string |
Date and time in UTC time that the Map was locked. |
|
|
mapType response string |
Identifies the Solution type and Map type. Types include:
Refer to Connector documents in TIBCO Scribe® Help to see which Map types are supported by the Source or Target Connection. Note: The following Map type has been deprecated: IntegrationServicesBasicMap |
|
|
modificationBy response string |
ID of the Agent that modified the Relationships. |
|
|
modifiedBy response string |
User name of the TIBCO Scribe® user who modified the Map. |
|
|
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. |
|
|
nativeQueryBlockID response string |
GUID / UUID of the test results for a Native Query Block. |
|
|
response boolean |
Indicates whether the Process only records created or updated since last run option is enabled. This option limits records processed to new and updated records. Used in conjuntion with the netChangeFieldName and the lastRunDate field. See Most Recent Record Processed in the TIBCO Scribe® Help.
|
|
|
response string |
Date field from the Source datastore used to determine if a record is new or has been updated. This date is compared to the date in the lastRunDate field. Used in conjunction with the Process only records created or updated since last run option in the netChange field. |
|
|
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 The name may extend multiple levels when accessing hierarchical data, such as, EntityFullName.RelatedEntityFullName.RelatedEntityFullName |
|
|
previewId response string |
GUID/UUID of the query preview. Use with GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{mapId}/previewquery/{previewId} method to view contents of the preview. |
|
|
processDefinitionDbId response string |
This field is not used. |
|
|
relatedEntities response string |
Data returned by a Query preview for an entity with related entities. For example, if the entity being queried is Account, it may have one or more related Contacts.
|
|
|
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 |
When you execute a single Map using the API, this field is returned with a null value. If you use the API to check the status of that execution, this field returns either . |
|
|
results response string |
Data returned by a Query preview. Maximum of 25 records.
|
|
|
revision response integer |
Revision number for a Map. Each time a Map is modified and saved, the revision number is incremented. Allows users to revert to a prior version of a Map, determine when a revision took place, and who modified the Map. |
|
|
revisionDate response string |
Date and time the revision was created in UTC time. |
|
|
severity response string |
Indicates the severity of an the error detected in one of the following:
Values include: error or warning. |
|
|
sourceConnectionAlias response string |
Connection name used by TIBCO Scribe® in the Operation Results for the Formula Editor. It is prepended to the name of the Block. For example, if you want to use the results of an UpdateInsert Block associated with a Salesforce target Connection named SF 1, in the Formula Editor under Operation Results you might see SF1_accountUpdateInsert. The Connection alias is SF1. |
|
|
sourceConnectionId response string |
GUID/UUID of the source Connection in the Map. |
|
|
sourceConnectionName response string |
Name of the source Connection in the Map. This name is user-specified when the Connection is created. |
|
|
sourceConnectionType response string |
Displays the name of the Connector for the source Connection, such as Eloqua, Microsoft SQL Server, or Microsoft Dynamics GP. See Connections in the TIBCO Scribe® Help for a complete list. |
|
|
sources response string |
Name of the source Connection in the Map. This name is user-specified when the Connection is created. |
|
|
startingBlockId response string |
ID of the first Block in the stack in an Integration Map. |
|
|
state response integer |
This field is not used. |
|
|
status response string |
Status of the Map execution. |
|
|
targetConnections response array |
Array of one or more target Connections and associated properties. Includes the following for each Connection:
|
|
|
targetFieldName response string |
Field name of the target field in a Map Block. Identifies a problem field during Map validation. |
|
|
targets response string |
Name of one or more target Connections in the Map. This name is user-specified when the Connection is created. |
|
|
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. |
|
|
url response string |
Endpoint URL for an Event Map. Each Map in an Event Solution has its own unique Endpoint URL. Properly formatted web calls to that URL cause the Map to run. The Endpoint URL is generated by TIBCO Scribe® the first time the Map is saved. See Defining An Event Message Map or Defining An Event Request/Reply Map in the TIBCO Scribe® Help. |
|
|
valid response boolean |
Indicates whether the Map is valid. Use the POST validate and POST validateformula endpoints to validate your Maps and GET validationresults to see whether the Map is valid.
|
|
|
response string |
Returned when validating a Map. Use this value with the Get Validation Results option, GET /v1/orgs/{orgId}/solutions/{solutionId}/maps/{validationId}/validationresults, to return whether the Map is valid or not. |
|
|
version response string |
Version of the Map schema. Should always be version 2.0 or higher. |
|
See