Core
Projects
Projects APIs form the foundation of Tray's comprehensive suite of endpoints designed to automate Software Development Life Cycle (SDLC) processes and facilitate environment promotion through a robust export-import mechanism. These APIs are particularly valuable for organizations implementing automated CI/CD pipelines for their projects.
The suite enables programmatic management of project versions, allowing teams to create, export, and import project states across different environments (from development to production).
This suite empowers teams implementing automated deployment pipelines by enabling:
- Automated environment promotion processes
- Consistent deployment procedures across environments
- Pre-deployment impact analysis
- Controlled rollback capabilities
- Configuration and dependency management across environments
The Project endpoints provide essential functionality across four key areas:
- Version Control: Create and list project versions to maintain a history of project states
- Environment Promotion: Export project versions from one environment and import them into another
- Pre-deployment Validation: Analyze requirements and preview changes before performing imports
- Dependency Management: Handle configuration mappings, authentications, and service connections during imports
Environment Promotion Overview
A typical environment promotion pipeline using these APIs follows these steps:
-
After completing development, create a project version in the source environment using the Create Project Version endpoint. This saves the current state of your integration.
-
Use the List Project Versions API to retrieve available versions and compare them if needed (similar to git diff functionality).
-
Once you've identified the desired version for promotion, use the Export Project from Version API to obtain the project version as JSON.
-
Before importing to the target environment:
- Use the Get Import Requirements API to identify necessary authentication and configuration mappings, to make sure all required mappings are available in your pipeline
- Use the Get Import Preview API to understand the impact of the import (optional but recommended, especially for embedded integrations as potential breaking changes will be highlighted at this step)
-
Import the project into the target environment using the Import Project API, providing the required environmental mappings (such as different authentications, custom services and connectors mappings or config values for the target environment).
-
After import, save a new version in the target environment (using Create Project Version API), ideally maintaining version number consistency with the source environment.
For embedded integrations, additional solution management steps are required after the project promotion process (please see the Solutions APIs documentation).
-
Use the Get Publish Preview API to validate the impact of publishing the updated solution (e.g. expected breaking changes)
-
Use the Publish Solution API to propagate changes to solution instances.
Platform deployment:
- Project import completes the promotion process
Embedded deployment:
- Project import updates the draft solution
- Publishing solution required to apply changes to existing solution instances
- May require manual solution instance upgrades in case of breaking changes
Import project
Import project with desired dependencies mappings (config, authentication, services, connectors can be specified)
Request Examples
{
"authenticationResolution": [
{
"authExportId": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"configOverride": {},
"exportedProjectJson": {},
"connectorMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
],
"serviceMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
]
}Response Examples
{
"importMetadata": {
"importedFrom": {
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"projectVersion": "string",
"projectName": "string"
},
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"projectName": "string"
},
"projectImpact": {
"config": {
"created": [
{
"key": "string",
"value": null
}
],
"updated": [
{
"key": "string",
"oldValue": null,
"newValue": null
}
],
"removed": [
{
"key": "string",
"value": null
}
]
},
"workflows": {
"created": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"importedFromId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"importedFromId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
]
}
},
"solutionImpact": {
"solutionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"changeType": "Created",
"breakingChanges": true,
"requiresNewUserInput": true,
"requiresNewSystemInput": true,
"authSlots": {
"created": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"recreated": true,
"slotRecreationReasons": [
{
"code": "AuthenticationIdChanged",
"message": "string"
}
],
"recreatedFromSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"previously": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true
}
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true
}
]
},
"configSlots": {
"created": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"recreated": true,
"slotRecreationReasons": [
{
"code": "ConfigVariableKeyChanged",
"message": "string"
}
],
"recreatedFromSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"previously": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true
}
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true
}
]
}
}
}Get import preview
Returns potential changes and impacts on the project and the solution (if applicable) if the import is applied.
Request Examples
{
"authenticationResolution": [
{
"authExportId": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"configOverride": {},
"exportedProjectJson": {},
"connectorMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
],
"serviceMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
]
}Response Examples
{
"importMetadata": {
"importedFrom": {
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"projectVersion": "string",
"projectName": "string"
},
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"projectName": "string"
},
"projectImpact": {
"config": {
"created": [
{
"key": "string",
"value": null
}
],
"updated": [
{
"key": "string",
"oldValue": null,
"newValue": null
}
],
"removed": [
{
"key": "string",
"value": null
}
]
},
"workflows": {
"created": [
{
"name": "string",
"importedFromId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"importedFromId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
]
}
},
"solutionImpact": {
"changeType": "Created",
"breakingChanges": true,
"requiresNewUserInput": true,
"requiresNewSystemInput": true,
"authSlots": {
"created": [
{
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"recreated": true,
"slotRecreationReasons": [
{
"code": "AuthenticationIdChanged",
"message": "string"
}
],
"recreatedFromSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"previously": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true
}
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"description": "string",
"authenticationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"serviceEnvironmentId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"scopes": [
"string"
],
"externalId": "string",
"static": true,
"hidden": true,
"skipCTA": true,
"requireUnique": true
}
]
},
"configSlots": {
"created": [
{
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"recreated": true,
"slotRecreationReasons": [
{
"code": "ConfigVariableKeyChanged",
"message": "string"
}
],
"recreatedFromSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
],
"updated": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true,
"hasBreakingChange": true,
"changes": [
{
"message": "string",
"code": "CreatedMandatorySlot",
"breakingChange": true
}
],
"previously": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true
}
}
],
"removed": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"title": "string",
"description": "string",
"externalId": "string",
"valueType": "string",
"ddl": true,
"ddlConfiguration": {
"allowSetCustomValue": true
},
"required": true,
"useDefaultValue": true,
"defaultValue": null,
"referencedAuthSlotId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"static": true,
"hidden": true,
"hasCustomJs": true,
"hasDataMapping": true,
"disabledResetType": true
}
]
}
}
}Get import requirements
Returns information describing required authentications and config mappings needed to complete an import
Request Examples
{
"exportedProjectJson": {},
"connectorMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
],
"serviceMapping": [
{
"from": {
"name": "string",
"version": "string"
},
"to": {
"name": "string",
"version": "string"
}
}
]
}Response Examples
{
"unresolvedAuthentications": true,
"newConfigKeys": true,
"config": {
"source": {},
"target": {}
},
"authenticationsRequirements": [
{
"authExportId": "string",
"title": "string",
"service": {
"name": "string",
"version": "string"
},
"scopes": [
"string"
],
"resolvedAuthentication": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"title": "string",
"service": {
"name": "string",
"version": "string"
},
"serviceEnvironment": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"scopes": [
"string"
]
}
}
]
}List project versions
Retrieve a list of saved versions of the project
Response Examples
{
"elements": [
{
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": "string",
"title": "string",
"description": "string",
"created": "2023-12-01T10:00:00Z",
"creator": "string"
}
],
"pageInfo": {
"startCursor": "string",
"endCursor": "string",
"hasNextPage": true,
"hasPreviousPage": true
}
}Create project version
Save a specific state of the project as version so that it can be later retrieved for release (or rollback)
Request Examples
{
"title": "string",
"description": "string"
}Response Examples
{
"projectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"versionNumber": "string",
"title": "string",
"description": "string",
"created": "2023-12-01T10:00:00Z",
"creator": "string"
}Export project from version
Retrieve a specific project version JSON
Response Examples
{
"message": "string",
"code": "string"
}