Update Shell
PUT /ws/rest/service/v2/admin/shell
Note:
- Oracle recommends delaying this REST call when reverse auto-population is configured in a business process (BP).
- In this REST call, Primavera Cloud Integration or Gateway Integration for P6 projects that are added under a shell can still be deleted with the same call, as long as the project has not synced yet. This behavior occurs because the same API payload is sent multiple times. On the first call, when the project does not exist, the API adds the project. On a later call with the same project data, the API deletes the existing unsynced project.
Purpose
The Update Shell REST service supports these options from the user interface:
- Currency: All currencies that you added
- Options: Phase, Email Address, Send Notifications To (list of emails), Document Manager Attribute Form, E-Signature Type, Time Zone, Financial Period, Template Name, Shell Manager Attribute Form
- Links: Your added links
- Default Calendar
- Custom Print Template
- Gateway Integration: Project ID
- Primavera Integration: Project ID
- View Forms: Form Name, Permission Structure
Note:
You can update only one shell per request.
Shell Additional Services: Delete and Reset Behavior
The services handled are:
- Links
- Options
- Images
- Gateway Integration
- Cloud Integration
Links
During shell update, the system deletes existing shell links before inserting the new links from the request.
This happens only when:
- The request contains valid link data.
- The operation is an update.
Options
The system does not delete options as rows. Instead, it resets specific fields to blank or null values.
- Project phase reset
- Time zone reset
- DM attribute form reset
- Notification users and groups reset
This reset occurs only when the request passes whitespace for those keys.
Notification users and groups replace the existing users and groups with the new set from the request.
Images
The system does not delete image records from Document Manager in this flow.
Rolling Image Association Removal
If an image file ID exists and the same ID appears again in the request, the system removes it from the list.
- If the ID does not exist, the system adds it.
- If the ID exists, the system removes it.
Gateway Integration
The system deletes gateway integration rows only for nonintegrated gateway projects.
- The requested P6 project ID exists in {{shell_p6_link}}.
- The existing row does not contain integrated project details.
If the project is already integrated, the system does not delete it and returns an error.
Cloud Integration - Cash Flow
Cash flow cloud integration supports repeated-request deletion.
- A cash flow project exists for the shell.
- The request sends the same project and workspace combination again.
Cloud Integration - Schedule / P6 Schedule
Schedule integration also supports removal when the request matches an existing schedule integration.
- Compare existing schedule integration rows with the request.
- Mark the matching integration for deletion.
- Check whether the project is already linked or synced before deletion.
- Block deletion if {{project_start_date}} is present.
Request Format
Send a request as a JSON Map with the following structure:
{
"options":{"shelltype": "<value>"},
"data":[]
}
To view a master list of all fields supported in the request:
- Go to the Company Workspace tab, and switch to Admin mode.
- In the left Navigator, select uDesigner, and then select Shell Manager.
- Open the [shell template].
- In the left Navigator, select Integration, and then select Detail.
The fields in the Detail menu apply to the Shell General tab.
Supported Request Parameter
The following request parameter is required:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| shelltype | Yes | String | The name of the shell template |
Optional Request Parameters Supported in uuu_shell_addl_props Key
To support all other tabs in the request, apart from the General tab, specify the uuu_shell_addl_props key in the following JSON map structure.
Note:
All fields in the uuu_shell_addl_props key are optional.
{
"uuu_shell_addl_props": {
"options": { },
"links": [ ],
"currency": [ ],
"images": { },
"gateway": [ ],
"cloud": [ ]
}
}
Options JSON Map Format in uuu_shell_addl_props Key
In the "options" JSON Map of the "uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"options": {
"projectPhase": "<value>",
"timezone": "<value>",
"financialPeriod": "<value>",
"notification": {
"users": []
"groups": []
},
"dmFormUsed": "<value>",
"eSign": "<value>",
"mailBoxId": "<value>",
}
}
}
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| projectPhase | No | String | Project Phase value |
| timezone | No | String | Time zone value |
| financialPeriod | No | String | Financial Period value |
| notification: users [ ] | No | String Array | List of usernames. For example, ["jdoe", "jsmith"] |
| notification: groups [ ] | No | String Array | List of groups. For example, ["Contractors", "Accommodation Managers"] |
| dmFormUsed | No | String | Document Manager value |
| eSign | No | String | e-Signature value. Valid values include: None, Default, DocuSign, Acrobat Sign. |
| mailBoxId | No | String | The Mailbox ID excluding the mail pattern. |
Links JSON Map Format in uuu_shell_addl_props Key
In the "links" JSON Map of the "uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"links": [
{
"orderId": 0,
"name": "",
"url": "",
}
]
}
}
If you specify the links JSON map, you can include the following parameters:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| name | Yes | String | URL name for the link. |
| url | Yes | String | URL for the link. |
| orderId | No | Integer | Specify the order of the links. An Incorrect value in the orderId changes the order value into 0. |
Currency JSON Map Format in uuu_shell_addl_props Key
In the "currency" JSON Map of
"uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"currency": [
{
"currencyCode": "",
"comments": "",
"rateType": "",
"rate": 0.0
}
]
}
}
If you specify the "currency" JSON map, you can include the following parameters:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| currencyCode | Yes | String | Currency code. |
| rateType | Yes | String | Indicate the rate type of the currency. Valid values include: FLOAT (default), PEG. |
| rate | No | Number, decimal supported. | Alter the currency rate only if the rateType is PEG. |
| comments | No | String | Specify currency details. |
Images JSON Map Format in uuu_shell_addl_props Key
In the "images" JSON Map of
"uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"images": {
"shell_images": [
{"file_name": "<value>", "title": "<value>"},
{"file_name": "<value>", "title": "<value>"}
],
"_attachment": {"zipped_file_content": "<value>", "zipped_file_name": "<value>", "zipped_file_size": 0},
"shell_images_from_dm": ["image1", "path/image2"]
}
}
}
If you specify the "images" JSON map, you can include the following parameters:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| file_name | Yes | String | Name of the file in the ZIP file. Valid values include: GIF, PNG, JPG, JPEG, TIF, TIFF. |
| title | Yes | String | New name to the image |
| zipped_file_content | Yes | String | Base64 content of the ZIP file |
| zipped_file_name | Yes | String | Original ZIP file name |
| zipped_file_size | Yes | Number | Original ZIP file size in bytes |
| shell_images_from_dm | Yes | String | Image name from the Document Manager |
Gateway JSON Map Format in uuu_shell_addl_props Key
In the "gateway" JSON Map of
"uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"gateway": [
{"p6_project_id": "<value>"},
{"p6_project_id": "<value>"}
]
}
}
If you specify the "gateway" JSON map, you can include the following parameters:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
p6_project_id
|
Yes | String | P6 project ID configured in the Primavera Gateway application. |
Cloud JSON Map Format in uuu_shell_addl_props Key
In the "cloud" JSON Map of
"uuu_shell_addl_props" key, you can include the following optional parameters:
{
"uuu_shell_addl_props": {
"cloud": [
{
"ext_project_id": "EVM268",
"ext_workspace_code": "OPCWORKSPACE",
"ext_project_name": "OPC03",
"integration_type": "Primavera Cloud Cash Flow"
}
]
}
}
If you specify the "cloud" JSON map, you can include the following parameters:
| Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
ext_project_id
|
Yes | String | Name of the Oracle Primavera Cloud project ID. |
| ext_workspace_code | Yes | String | Workspace name. |
| ext_project_name | Yes | String | Project name. |
| integration_type | Yes | String |
The project type is Cashflow or Schedule. Valid values include: Primavera Cloud Cash Flow, Primavera Cloud Schedule, and P6 Schedule. |
Response Format
A JSON object is returned in the following format:
{
"data": [],
"message": [<list of messages>],
"status": <REST status code value>,
"rest_audit_id": "Value"
}
Sample Success Request
This example shows a successful request with status code 200.
{
"options": { "shelltype": "Building Properties - CBS" },
"data": [
{
"uBuildingNumber": "BLDCBS - 0004",
"uuu_shell_status": "Active",
"uuu_shell_addl_props": {
"gateway": [{"p6_project_id": "EVM243"}, {"p
6_project_id":
"EVM244"}],
"links": [{"orderId": 1, "name": "Google", "url": "http://www.google.com"}],
"options": {
"dmFormUsed": "Folder and Document Attributes",
"financialPeriod": "FP1",
"eSign": "Default",
"projectPhase": "Preplanning",
"timezone": "(UTC-12:00) International Date Line West",
"notification": {"users": ["tt"],"groups": ["Accommodation Managers"]},
},
"currency": [
{"currencyCode": "JPY",
"comments": "Metadata for the currency value",
"rateType": "PEG",
"rate": 150.0503
}
],
"images": {
"shell_images": [
{"file_name": "Image_1.png", "title": "image one"},
{"file_name": "Image_2.png", "title": "image two"}
],
"_attachment": {
"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAA",
"zipped_file_name": "Image.zip",
"zipped_file_size": 15657
},
"shell_images_from_dm": ["image1.png", "/Sample/image2.jpg"]
},
"cloud": [
{
"ext_project_id": "OPC03",
"ext_workspace_code": "OPCWORKSPACE",
"ext_project_name": "OPC03",
"integration_type": "Primavera Cloud Cash Flow"
}
]
}
}
]
}
Sample Success Response
This example shows a successful response with status code 200.
{
"data": [
{"uBuildingNumber": "BLDCBS - 0004",
"uuu_shell_status": "Active",
"uuu_shell_addl_props": {
"cloud": [
{
"ext_project_id": "OPC03",
"ext_project_name": "OPC03",
"integration_type": "Primavera Cloud Cash Flow",
"ext_workspace_code": "OPCWORKSPACE"
}
],
"images": {
"shell_images": [ {"file_name": "Image_1.png", "title": "image one"},
{"file_name": "Image_2.png", "title": "image two"}
],
"_attachment": {
"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAA",
"zipped_file_size": 15657,
"zipped_file_name": "Image.zip"
},
"shell_images_from_dm": ["image1.png", "/Sample/image2.jpg"]},
"options": {
"dmFormUsed": "Folder and Document Attributes",
"financialPeriod": "FP1",
"eSign": "Default",
"projectPhase": "Preplanning",
"timezone": "(UTC-12:00) International Date Line West",
"notification": {
"users": ["tt"],
"groups": ["Accommodation Managers"]
},
},
"links": [
{"orderId": 1, "name": "Google", "url": "http://www.google.com"}
],
"currency": [
{
"rateType": "PEG",
"comments": "Metadata for the currency value",
"rate": 150.0503,
"currencyCode": "JPY"
}
],
"gateway": [{"p6_project_id": "EVM243"}, {"p6_project_id": "EVM244"}]
}
}
],
"message": [{"uBuildingNumber": "BLDCBS - 0004", "_record_status": "SUCCESS"}],
"status": 200,
"rest_audit_id": 9080
}
Sample Failed Request
This example shows a failed request to update a shell.
{
"options": { "shelltype": "Building Properties - CBS" },
"data": [
{
"uBuildingNumber": "BLDCBS - 0004",
"uuu_shell_status": "Active",
"uuu_shell_addl_props": {
"gateway": [ {"p6_project_id": "EVM242"}, {"p6_project_id": "EVM241"}],
"links": [{"orderId": 1, "name": "Google", url": "h://www.google.com"}],
"options": {"dmFormUsed": "Folder and Dcument Attributes",
"financialPeriod": "FP",
"eSign": "Default",
"projectPhase": "Preplaning",
"timezone": "(UTC-12:00)International Date Line West",
"notification": {
"users": ["tts"],
"groups": ["Accommodation Managers"]
},
},
"currency": [{"currencyCode": "",
"comments": "Metadata for the currency value",
"rateType": "PEG",
"rate": 150.0503}
],
"images": {"shell_images": [
{"file_name": "Image_1.pg", "title": "image one"},
{"file_name": "Image_10.png", "title": "image two"}
],
"_attachment": {"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAASW1h",
"zipped_file_name": "Image.zip",
"zipped_file_size": 15657
}
},
"cloud": [{
"ext_project_id": "OPC04",
"ext_project_name": "OPC04",
"integration_type": "Primavera Cloud Schedule",
"ext_workspace_code": "OPCWORKSPACE"}
]
}
}
]
}
Sample Failed Response
This example shows a failed response with status code 3000 and a list of errors.
{
"data": [{
"uBuildingNumber": "BLDCBS - 0004",
"uuu_shell_status": "Active",
"uuu_shell_addl_props": {
"cloud": [
{"ext_project_id": "OPC04",
"ext_project_name": "OPC04",
"integration_type": "Primavera Cloud Schedule",
"ext_workspace_code": "OPCWORKSPACE"
}],
"images": {
"shell_images": [ {"file_name": "Image_1.pg", "title": "image one"},
{"file_name": "Image_10.png", "title": "image two"}
],
"_attachment": {"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAASW1h",
"zipped_file_size": 15657,
"zipped_file_name": "Image.zip"
}
},
"options": { "dmFormUsed": "Folder and Dcument Attributes",
"financialPeriod": "FP",
"eSign": "Default",
"projectPhase": "Preplaning",
"timezone": "(UTC-12:00)International Date Line West",
"notification": {"groups": ["Accommodation Managersss"]},
},
"links": [{"orderId": 1, "name": "Google", "url": "h://www.google.com"}],
"currency": [{
"rateType": "PEG",
"comments": "Metadata for the currency value",
"rate": 150.0503,
"currencyCode": ""
}],
"gateway": [{"p6_project_id": "EVM242"},{"p6_project_id": "EVM241"}]
}
}
],
"message": [{
"uBuildingNumber": "BLDCBS - 0004",
"_record_status": "Shell creation failed because of errors found while processing the additional shell options",
"errors": [
"url is invalid; cannot exceed 250 chars",
"Same project available in the other shells: (EVM242 -> W_BUILDING_CBS 0006), (EVM241 -> W_BUILDING_CBS 0006)",
"Invalid project phase",
"currencyCode is a required field",
"Multiple cashflow projects cannot be added",
"Invalid timezone",
"DM name does not exist",
"Non-image files found in the request"
]
}],
"status": 3000,
"rest_audit_id": 9083
}
Supported Validation Messages and Status Codes
The following error messages and status codes display in the response when incorrect values are provided in the request.
| Field Name | Use-case Scenario | Status code | Error Message |
|---|---|---|---|
| shelltype | The key is missing or an incorrect shell template name is given. | 813 | Invalid shell type. |
| projectPhase | Project phase is not found with the given value. | 3000 | Invalid project phase. |
| projectPhase | Multiple values are found with the given value. | 3000 | Multiple project phase found. |
| timezone | Time zone is not found with the given value. | 3000 | Invalid timezone. |
| timezone | Multiple time zones are found with the given value. | 3000 | Multiple timezone entries found. |
| financialPeriod | Financial period is not found with the given value. | 3000 | Financial period does not exist. |
| financialPeriod | Cashflow curve data is associated with the financial period being updated. | 3000 | Cash flow Curves are already referring to Financial Period, Can't modify: <FP Name>. |
| financialPeriod | EVM analysis data is associated with the financial period being updated. | 3000 | Earned Value Analysis Graphs are referring to Financial Period, Can't modify: <FP Name. |
| notification users [] | An invalid user is given in the request. | 3000 | User(s) do not have access or not found: <user1>, <user2>, ... |
| notification groups [] | An invalid group name is given in the request. | 3000 | Group(s) do not have access or not found: <user1>, <user2>, ... |
| dmFormUsed | No document manager is found with the given value. | 3000 | DM name does not exist. |
| eSign | eSign is not configured in the company workspace. | 3000 | Requested E-Signature not configured. |
| eSign | an invalid eSign is given in the request. | 3000 | Invalid e-sign. |
| mailBoxId | The email prefix is invalid or wrong. | 3000 | Invalid mailBox ID. |
| mailBoxId | The same project email is already taken. | 3000 | Duplicate project email found. |
| name | The name is given empty/null or not present. | 3000 | Name is a required field. |
| name | The name is more than 50 characters. | 3000 | Name is invalid; cannot exceed 50 chars. |
| url | The url is given empty/null or not present. | 3000 | URL is a required field. |
| url | The url is more than 250 characters or in incorrect format. | 3000 | URL is invalid; cannot exceed 250 chars. |
| currencyCode | The currencyCode is given empty/null or not present. | 3000 | currencyCode is a required field |
| currencyCode | The currencyCode is invalid. | 3000 | Currency exchange rates are not available |
| currencyCode | Altering the base currency of the project. | 3000 | Update to the currency is not allowed because it matches Company Currency. |
| currencyCode | Multiple currency details available for same currency code. | 3000 | Duplicate currency found in the request |
| currencyCode | Unable to find the company currency. | 3000 | Unable to find the Company Currency. |
| rate | The rateType is PEG, and no rate value is provided. | 3000 | Rate value for the PEG type is not a number. |
| comments | Comments exceed 250 characters. | 3000 | Comments are invalid; cannot exceed 250 chars. |
| file_name | An invalid request is found in the request. | 3000 | Invalid JSON structure found in the request for additional properties. |
| file_name | File_name is missing. | 3000 | file_name and title are required for shell images. |
| file_name | Other image formats are included. | 3000 | File upload prevented due to blocked file extension. |
| title | New name of the image. | 3000 | file_name and title are required for shell images. |
| zipped_file_content | zip contains non-images. | 3000 | Non-image files found in the request. |
| zipped_file_content | zip does not contain the image. | 3000 | No images found in the ZIP file. |
| zipped_file_content | Issue with unzipping the file. | 3000 | Unable to unzip the files. |
| zipped_file_content | An invalid attachment is available. | 3000 | Invalid attachment found in the request. |
| zipped_file_size | A mismatch with the file size in the request. | 3000 | File size is mismatched with the incoming file. |
| shell_images_from_dm | multiple images found with the same name in the DM. | 3000 | Multiple image(s) found with the same name from DM: <image1>, <image2>, ... |
| shell_images_from_dm | Image is not found with the given name. | 3000 | No image(s) found with the name from DM: <image1>, <image2>,... |
| p6_project_id | invalid request is found in the request. | 3000 | Invalid JSON structure found in the request for additional properties |
| p6_project_id | p6_project_id is null/missing/empty string. | 3000 | p6_project_id is a required field |
| p6_project_id | EVM license is not provided. | 3000 | Invalid EVM License |
| p6_project_id | Cloud schedule project exists. | 3000 | Cloud schedule project exists |
| p6_project_id | Duplicate project ID available in the request. | 3000 | Same project is available multiple times in the same shell: <id1>, <id2>, ... |
| p6_project_id | Attempt to delete the integrated project. | 3000 | Unable to delete the project as it is integrated |
| p6_project_id | Same project is available in other shells. | 3000 | Same project available in the other shells: EVM > shell name, ... |
| ext_project_id | An invalid request is included in the request. | 3000 | Invalid JSON structure found in the request for additional properties |
| ext_project_id | ext_project_id is null/missing/empty string. | 3000 |
ext_project_id is a required field.
|
| ext_project_id | Schedule project is integrated already. | 3000 | Unable to delete the project as its linked |
| ext_project_id | Multiple cashflow projects are added. | 3000 | Multiple cashflow projects cannot be added |
| ext_project_id | Duplicate project ID is included in the request. | 3000 | Found duplicate cloud projects in the request |
| ext_project_id | Cloud schedule project added when Gateway project exists. | 3000 | Gateway project exists |
| ext_project_id | No projects are configured in the Construction and Engineering Lobby | 3000 | No lobby projects configured in the system. |