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":[]
}
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 are applicable to the Shell General tab.
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 |
|---|---|---|---|
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, the following parameters can be included:
| 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 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"}, {"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 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 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. |