Update Shell
PUT /ws/rest/service/v2/admin/shell
Note: As a best practice, delay invoking this REST call when reverse auto-population is configured in a business process.
Purpose
The Update Shell REST service supports all options available through the user interface, including:
- 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: Only one shell can be updated per request.
Request Format
Send a request as a JSON Map with the following structure:
{
"options":{"shelltype": "<value>"},
"data":[]
}
Supported Request Parameter
The following request parameter must be included:
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 key, uuu_shell_addl_props, 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 "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 "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, the following parameters can be included:
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, the following parameters can be included:
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, the following parameters can be included:
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, the following parameters can be included:
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| 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, the following parameters can be included:
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
| 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.
|
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 is an example of 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"}, {"p6_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 is a successful response to the above request 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 is an example of 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 is an example of a failed response with status code 3000, with a list of errors displayed below.
{
"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/ext_project_name/ext_workspace_code 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 lobby | 3000 | No lobby projects configured in the system. |
ext_workspace_code | ext_workspace_code is null/missing/empty string | 3000 | ext_project_id/ext_project_name/ext_workspace_code is a required field. |
ext_project_name | ext_project_name is null/missing/empty string | 3000 | ext_project_id/ext_project_name/ext_workspace_code is a required field. |
Related Topics
Last Published Tuesday, April 15, 2025