Project API

Projects can be accessed through this API using the GET service.

Authentication - Use Basic Authentication for this API.

Valid Source Control Management Types

Source Control Management SystemJSON String Representation
ClearCase Unified Control Management"CCUCM"
Concurrent Version System"CVS"
Git"GIT"
File System"FILE"
Perforce"PERF"
Polytron Version Control System"PVCS"
Subversion"SVN"
Team Foundation Version Control"TFVC"

Valid Project Types

Project TypeJSON String Representation
General"GENERAL"
Managed File Transfer"MFT"
Partial File"PARTIAL_FILE"
Oracle Forms"OracleForms"
Oracle Database"ORACLE_DB"
Oracle Business Intelligence"ORACLE_BI"
Sales Force"SALESFORCE"
Utility"UTILITY"
Generic"GENERIC"

Valid Priority Scope Types

Priority Scope TypesJSON String Representation
Application"Application"
Folder"Folder"
Global"Global"

GET

There are two implementations of GET. One will find a Project with the given Id and return the JSON representation of the Project. The other will find a list of Projects matching the parameters supplied to it.

GET (Using Id)

This GET service will find a Project by Id and return a JSON representation of it.

API URLs

http://host:port/flexdeploy/rest/v1/project/{id}

Request

Parameter
Required
Type
Description
idYesURLThis is a URL path parameter for the id which is used to find a project.

Response

AttributesTypeDescription
projectNameStringThis is the name of the project.
applicationIdStringThis is the type of the project.
projectPathStringFully qualified project path.
isActiveBooleanThis is a Boolean that tracks whether or not the project is active. Null input defaults to true.
descriptionStringThis is the group of the project.
partialDeploymentBooleanThis is the subgroup of the project. Null input defaults to false.
priorityIntegerThis is the description of the project.
projectTypeStringThis is the id of the active version of the workflow. Must be a valid project type.
scmTypeStringThis specifies the source control management system used by this project. Must be a valid source control management system.
priorityScopeStringThis specifies the priority scope of the current project. Either 'Global', 'Folder' or 'Application'
buildWorkflowIdLongThis Long specifies the id of the build workflow used by this project.
buildInstanceIdLongThis id the build instance used by this project.
utilityWorkflowIdLongThis id specifies the utility workflow used by this project.
utilityInstanceIdsList<Long>This id specifies the utility instance used by this project.
deployWorkflowIdLongThis id specifies the deployment workflow used by this project.
deployInstanceIdsList<Long>This is a list of id's which identify the deployment instances for this project.
streamsList<Long>This is a list of id's which identify the Project Streams associated with this project.

Response Codes

HTTP CodeDescription
200Projects were found and returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

If we had a Project in our database with the name 'Project1' with the following attributes:

Project - "Project1"
{
   "priority": 1,
   "projectName": "Project1",
   "description": "Our thoughts become our words. Our words become our actions.",
   "applicationId": 10001,
   "priorityScope": "Application",
   "partialDeployment": false,
   "isActive": true,
   "scmType": "NONE",
   "streams": [
      10802,
      10803,
      10804,
      10805
   ],
   "deployWorkflowId": 10873,
   "deployInstanceIds": [
      11153,
      11168,
      11183,
      11198,
      11213,
      11228,
      11243
   ],
   "buildWorkflowId": 10869,
   "buildInstanceId": 11153,
   "projectType": null
}

When we run a GET request at the following URL:

http://host:port/flexdeploy/rest/v1/project/10002

The GET request would return the  following JSON project object

GET JSON Response
{
   "priority": 1,
   "projectName": "Project1",
   "description": "Our thoughts become our words. Our words become our actions.",
   "applicationId": 10001,
   "priorityScope": "Application",
   "partialDeployment": false,
   "isActive": true,
   "scmType": "NONE",
   "streams": [
      10802,
      10803,
      10804,
      10805
   ],
   "utilityWorkflowId": 11434,
   "utilityInstanceIds": [11275],
   "deployWorkflowId": 10873,
   "deployInstanceIds": [
      11153,
      11168,
      11183,
      11198,
      11213,
      11228,
      11243
   ],
   "buildWorkflowId": 10869,
   "buildInstanceId": 11153,
   "projectType": null
}

Get(Using Query Parameters)

This GET service will find a project by querying based on a name and application id and return the JSON representations of the objects. If no query parameters are given this request will return the entire list of projects.

API URLs

http://host:port/flexdeploy/rest/v1/project?
Append the following character sequences to the above URL to specify Query parameters. Use '&' between successive query parameters:

  • projectName={name}
  • applicationId={applicationid}
  • folderPath={folderPath}
  • isActive={isActive}

folderPath Format

  • Path parameters are separated by slashes(forward or backward).
  • Trailing slashes will be ignored.
  • Single leading slashes are ignored.
  • To access a folder or application, it's full path from the project archive root folder must be used.
  • A shorted path is valid, but will return more results.
  • The project archive root folder is an optional path parameter.
  • Folders and applications are considered path parameters.
  • Forward and backward slashes are accepted
  • Project names are not considered path parameters. For example,
    • The folderPath used to access the 'AccountingApps' application :
    • /Flexdeploy/CommerceProjects/AccountingApps/
      • or
    • CommerceProjects\AccountingApps
    • i.e. you can omit FlexDeploy at start of folderPath

Examples:

The query parameters are not case sensitive. Searching by projectName=NAME is the same as searching by projectName=name.

Request

Parameter
Required
Type
Description
projectNameNoQuery - String

This is a URL query parameter for the name which is used to query the projects with.

Contains ignore case search

applicationIdNoQuery - LongThis is a URL query parameter for application id which is used to query the projects within an application.
folderPathNoQuery - String

This is a URL query parameter which specified the path of the desired folders (and optionally the application, but not the project name)

All projects in provided path will be considered, i.e. including any sub folders of provided path as well.

isActive


NoQuery - Boolean

@Since 5.1.0.2

This is a URL query parameter which specifies whether returned projects should only include active or inactive projects.

If this parameter is not provided, both active and inactive projects may be returned.

Response

AttributesTypeDescription
projectNameStringThis is the name of the project.
applicationIdStringThis is the type of the project.
projectPathStringFully qualified project path.
isActiveBooleanThis is a Boolean that tracks whether or not the project is active. Null input defaults to true.
descriptionStringThis is the group of the project.
partialDeploymentBooleanThis is the subgroup of the project. Null input defaults to false.
priorityIntegerThis is the description of the project.
projectTypeStringThis is the id of the active version of the workflow. Must be a valid project type.
scmTypeStringThis specifies the source control management system used by this project. Must be a valid source control management system.
priorityScopeStringThis specifies the priority scope of the current project. Either 'Global', 'Folder' or 'Application'
buildWorkflowIdLongThis Long specifies the id of the build workflow used by this project.
buildInstanceIdLongThis id the build instance used by this project.
utilityWorkflowIdLongThis id specifies the utility workflow used by this project.
utilityInstanceIdsList<Long>This id specifies the utility instance used by this project.
deployWorkflowIdLongThis id specifies the deployment workflow used by this project.
deployInstanceIdsList<Long>This is a list of id's which identify the deployment instances for this project.
streamsList<Long>This is a list of id's which identify the Project Streams associated with this project.

Response Codes

HTTP Code
Description
200Search successful and results returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

If we had Projects in our database with the names 'Project1' and 'Project2' and the following attributes:

Project - "Project1"
{
   "priority": 1,
   "projectName": "Project1",
   "description": "Our thoughts become our words. Our words become our actions.",
   "applicationId": 10001,
   "priorityScope": "Application",
   "partialDeployment": false,
   "isActive": true,
   "scmType": "NONE",
   "streams": [
      10802,
      10803,
      10804,
      10805
   ],
   "utilityWorkflowId": 11434,
   "utilityInstanceIds": [11275],
   "deployWorkflowId": 10873,
   "deployInstanceIds": [
      11153,
      11168,
      11183,
      11198,
      11213,
      11228,
      11243
   ],
   "buildWorkflowId": 10869,
   "buildInstanceId": 11153,
   "projectType": null
}
Project - "Project2"
{
   "priority": 1,
   "description": "No Permissions",
   "applicationId": 10001,
   "isActive": true,
   "scmType": "SVN",
   "projectType": null,
   "projectName": "Project2",
   "streams": [],
   "priorityScope": "Application",
   "partialDeployment": false,
   "utilityWorkflowId": null,
   "utilityInstanceIds": null,
   "deployWorkflowId": null,
   "buildWorkflowId": null,
   "deployInstanceIds": null,
   "buildInstanceId": null
}

When we run a GET request at the following URL

http://host:port/flexdeploy/rest/v1/project?applicationId=10001

The GET request would return the  following JSON workflow object

{
   "priority": 1,
   "description": "No Permissions",
   "applicationId": 10001,
   "isActive": true,
   "scmType": "SVN",
   "projectType": null,
   "projectName": "Project2",
   "streams": [],
   "priorityScope": "Application",
   "partialDeployment": false,
   "utilityWorkflowId": null,
   "utilityInstanceIds": null,
   "deployWorkflowId": null,
   "buildWorkflowId": null,
   "deployInstanceIds": null,
   "buildInstanceId": null
}

POST

Build Project (Using Id)

This POST service will perform the same action found on the Build Request Form. It will initiate a request to build the project with the given Id. The service will return workflow request. Workflow request id from return data can be used with Workflow Request API to determine when the execution is complete.

This page includes examples for Full and Partial deploy project builds.

API URLs

http://host:port/flexdeploy/rest/v1/project/(Id)/build

Request

  • If trying to build a Partial Deploy project with all of the files in the repository (equivalent to Build - All Files button in the UI), then simply remove the "projectFiles" list, and the REST API will detect that the project is meant for partial deploys automatically and perform the build with all of the files.

Parameter

Required

Type

Description

environmentIdY

Long

This is the environment Id, not the environment name that you see on most screens.

streamId

Y

Long

The Id of the Stream.

forceBuild

N

Boolean

Values are true or false. Indicates that the build should occur even if there are not SCM changes. Defaults to false.

relatedTicketsNStringList of Issue Tracking System tickets.
workflowVersionOverride

N

String

Optionally the version of the workflow can be overridden. Defaults to the currently active version.

inputs

N

List<Input>

See Common Parameters below.

flexFieldsNList<FlexField>See Common Parameters below.
projectFilesNList<ProjectFile>

Only for partial deployment project builds.

An array of objects with 2 fields each: path and scmRevision.

packageNameNString

Only for partial deployment project builds.

Unique name to identify a build for partial deployments project. Defaults to the project version if no value is provided.

If packageName is provided without projectFiles, files configured in that package will be used.

If packageName is provided with projectFiles, then input is used for build and package definition is updated with this projectFiles list.

If packageName and projectFiles are not provided for partial deployment project, then All Files build will be performed.

releaseIdNStringId of the release to which this build is related to. If specified, a new snapshot is going to be created.

Input

This is a list of code/value pairs for the inputs. Not all inputs need to be supplied. If an input has a default value that is acceptable for the Workflow to run, it does not need to be supplied.

Attribute
RequiredType
Description
codeYStringThe code of the Input
valueNString

The value of the Input

FlexField

This is a list of the code/value pairs for the FlexFields (not the Display Name). Not all FlexFields need to be supplied. If a FlexField has a default value or options that are acceptable for the workflow to run, it does not need to be changed.

Attribute
RequiredType
Description
codeYStringThe code of the FlexField
valueNString

The value of the FlexField

ProjectFile

Attribute
RequiredType
Description
pathYStringFully qualified file path that is required inside the projectFiles parameter.
scmRevisionNLong

Optionally include the revision number that you would like to use for the build.

If it is not indicated, then FlexDeploy will use the latest revision as the default.

Response

Attributes

Type

Description

warningMessageString

Indicates any warning message in the event where the request was successful but no build was initiated.  

For example: No changes found in source control

warningCodeStringMatching warning code for the warning message.  

workflowRequests

Array

Array of workflow request objects

Response Codes

HTTP Code
Description
200No changes were detected, no build initiated.
201Project was built successfully
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Project not found
500Unexpected internal server error

Example

We can build a Project with Id 10004 with this request:

API URLs

http://host:port/flexdeploy/rest/v1/project/10004/build

Sample JSON Request

{
    "environmentId": 11101 ,
    "forceBuild": true,
    "workflowVersionOverride": null,
    "streamId": 11210,
    "inputs": [
    {
        "code":"input1","value": "xyz"
    },
    {
        "code":"input2","value": "123"
    }],
    "projectFiles":[
    {
        "path": "/java/xxt/oracle/xxPersonMainCO.java"
    },
    {
       "path": "/java/xxt/oracle/apps/managePersonCO.java",
       "scmRevision": "1515"
    }],
    "packageName": "ALM150",
    "relatedTickets": null,
    "flexFields": [{
        "code": "Build FlexField" ,
        "value": 10
    }],
    "releaseId": 27003
}

In response, we will receive an array of workflowRequests

{
    "warningMessage": null,
    "warningCode": null,
    "workflowRequests": [
        {
            "packageName": null,
            "folderName": "Human Resources",
            "releaseSnapshotId": null,
            "workflowRequestStatus": "READY",
            "folderId": 10001,
            "exceptionToWindow": false,
            "releaseDefinitionId": null,
            "cmsissues": "",
            "workflowRequestId": 12019,
            "projectName": "ProcessHRRequest",
            "projectStreamId": 10502,
            "projectVersionName": "1.0.9",
            "requestAllFiles": false,
            "projectVersionId": 30001,
            "environmentId": 11016,
            "folderRequestId": null,
            "flexFields": [],
            "folderPath": "FlexDeploy/Human Resources",
            "projectId": 10501,
            "requestedBy": "fdadmin",
            "requestedStartTime": null,
            "force": false,
            "stopOnPackageError": null,
            "workflowOverrideVersion": null,
            "folderVersionId": null
        }
    ]
}

Deploy Project (Using Id)

This POST service will perform the same action found on the Deployment Request Form off the project screen. It will initiate a request to deploy the project specified with the project Id. The service will return workflow request. Workflow request id from return data can be used with Workflow Request API to determine when the execution is complete.

API URL

http://host:port/flexdeploy/rest/v1/project/{Id}/deploy

Request

ParameterRequiredTypeDescription
environmentIdYLongThis is the environment id, not the environment name that is seen on most screens.
instanceIdsNArray of Long

The list of instances where the deployment will occur. Make sure to enter the instance id, not the instance name that is seen on most screens.

If not provided, all deploy instances configured for Project will be used for deployment.

projectIdYLongThe Id of the project to deploy.
packageDetailsN*Array of PackageInfo

This is required for partial deployments, but not for full deployments.

Included to indicate what should be deployed in a partial deployment.

See more info on PackageInfo below.

forceDeployNBooleanValues are true or false. Indicates that the deployment should occur even when the projectVersionId is already deployed to that instance. Defaults to false.
exceptionToWindowNBooleanValues are true or false. Indicates that the deployment is an exception to the deployment window. Defaults to false.
projectVersionIdNLongThe id of the project version to be deployed. If not specified, the most recently built projectVersionId will be deployed.
startTimeNString

The time when the deployment will be started. Format should yyyy-MM-dd'T'HH:mm:ssXXX.

For example, 2019-03-16T21:17:52-06:00

workflowVersionOverrideNStringOptionally, the version of the workflow can be overridden.
inputs NArraySee Common Parameters below.
flexFieldsNArraySee Common Parameters below.
changeTicketsNArray of StringTicket number for the given deployment, using the configured Change Management System.

Input

This is a list of code/value pairs for the workflow inputs. Not all inputs need to be supplied. If an input has a default value that is acceptable for the workflow to run, it does not need to be supplied.

AttributeRequiredTypeDescription
codeYStringThe code of the input
valueNStringThe value of the input

FlexField

This is the list of the code/value pairs for the FlexFields (not the display name). Not all FlexFields need to be supplied. If a FlexFields has a default value or options that are acceptable for the workflow to run, it does not need to be changed.

AttributeRequiredTypeDescription
codeYStringThe code of the FlexField
valueNStringThe value of the FlexField

PackageInfo

AttributeRequiredTypeDescription
packageNameNStringThe name of the package to deploy. If blank, all files will be assumed.
priorityNIntegerThe priority of the package. If it is not indicated, then FlexDeploy will deploy the packages in the order they are provided in the JSON request.
projectVersionIdY*LongThe id of the project version to deploy. This parameter is not required if useLatestPackageVersion is true.
useLatestPackageVersionNBooleanUses the most recent package version. Defaults to false.

Response

AttributeTypeDescription
warningMessageString

Indicates any warning message in the event where the request was successful but no new deployment was initiated.  

For example: Project Version is already deployed and force deploy wasn't specified

warningCodeStringMatching warning code for the warning message.  
workflowRequestsArray

Array of workflow request objects

Response Codes

HTTP CodeDescription
200Project version already deployed
201Deploy request initiated successfully
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Project not found
500Unexpected internal server error

Example Deploy Request

We can deploy a project with Id 10004 with the following request:

API URLs

http://host:port/flexdeploy/rest/v1/project/10004/deploy

{
	"instanceIds":[100001],
	"environmentId":12345,
	"forceDeploy":"false",
	"inputs":
	[
		{
			"code":"RESTART_SEVER",
			"value":"true"
		},
		{
			"code":"COMMENT",
			"value":"Deploying from REST API"
		}
	]
}

In response, we will receive an array of workflowRequests:

{
    "warningMessage": null,
    "warningCode": null,
    "workflowRequests": [
        {
            "packageName": null,
            "folderName": "Human Resources",
            "releaseSnapshotId": null,
            "workflowRequestStatus": "READY",
            "folderId": 10001,
            "exceptionToWindow": false,
            "releaseDefinitionId": null,
            "cmsissues": "",
            "workflowRequestId": 12001,
            "projectName": "ProcessHRRequest",
            "projectStreamId": 10502,
            "projectVersionName": "1.0.8",
            "requestAllFiles": false,
            "projectVersionId": 29201,
            "environmentId": 11210,
            "folderRequestId": null,
            "flexFields": [],
            "folderPath": "FlexDeploy/Human Resources",
            "projectId": 10501,
            "requestedBy": "fdadmin",
            "requestedStartTime": null,
            "force": true,
            "stopOnPackageError": null,
            "workflowOverrideVersion": null,
            "folderVersionId": null
        }
    ]
}

Execute Utility Project (Using Id)

This POST service will perform the same action found on the Execute Utility Project Request Form off the project screen. It will initiate a request to execute the project with the Project ID specified in the URL. The service will return workflow request. Workflow request id from return data can be used with Workflow Request API to determine when the execution is complete.

API URLs

http://host:port/flexdeploy/rest/v1/project/{id}/execute

Request

Attributes

Required

Type

Description

idYURLThis is a URL path parameter for the id which is used to execute a project.

environmentId

Y

Long

The Id of the Environment the project should be executed in.

instanceIds

N

List<Long>

A list of Instance Ids that the project should be executed on. If not supplied, the project will execute on the instances that are associated to the utility project.

exceptionToWindow

N

Boolean

Values are true or false. Indicates that the deployment is an exception to the deployment window. Defaults to false.

startTime

N

DateTime

The time when the deployment will be started. The expected time format is: yyyy-MM-dd'T'HH:mm:ssXXX

workflowVersionOverride

N

String

Optionally, specify a workflow version to override the active workflow version.

inputs

N

Array

This is a list of code/value pairs for the inputs. Not all inputs need to be supplied. If an input has a default value that is acceptable for the Workflow to run, it does not need to be supplied.

flexFields

N

Array

This is a list of the code/value pairs for the Flexfields. Not all FlexFields need to be supplied. If a FlexField has a default value or options that are acceptable for the workflow to run, it does not need to be changed.

Response

Attributes

Type

Description

warningMessageString

Indicates any warning message in the event where the request was successful but no execution was initiated.  

warningCodeStringMatching warning code for the warning message.  

workflowRequests

Array

Array of workflow request objects

Response Codes

HTTP CodeDescription
201Project was found and executed
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

We can execute a Utility Project with Id 10004 with this request:

URL: http://host:port/flexdeploy/rest/v1/project/10004/execute

{
	"environmentId":10045,
	"instanceIds":[10044],
	"exceptionToWindow":false,
	"startTime":"2018-07-20T11:31:06Z",
	"workflowVersionOverride":"1.0",
	"inputs":[
		{"code":"INPUT1","value":"Test"},
		{"code":"INPUT2","value":"1234"}
	],
	"flexFields":[
		{"code":"FLEXFIELD1","value":"123"},
		{"code":"FLEXFIELD2","value":"abc"}
	]
}

In response, we will receive an array of workflowRequests:

{
    "warningCode": null,
    "warningMessage": null,
    "wfrequests": [
        {
            "packageName": null,
            "workflowOverrideVersion": null,
            "stopOnPackageError": null,
            "workflowRequestStatus": "READY",
            "exceptionToWindow": false,
            "projectName": "Util",
            "workflowRequestId": 11819,
            "requestAllFiles": false,
            "projectStreamId": 29802,
            "projectVersionName": "1.0.1",
            "projectVersionId": 29809,
            "environmentId": 11210,
            "folderRequestId": null,
            "folderPath": "FlexDeploy/HR Utils",
            "flexFields": [],
            "projectId": 29801,
            "folderId": 10001,
            "requestedStartTime": null,
            "folderVersionId": null,
            "folderName": "HR Utils",
            "requestedBy": "fdadmin",
            "releaseDefinitionId": null,
            "cmsissues": "",
            "force": true,
            "releaseSnapshotId": null
        }
    ]
}