Create Shell
POST /ws/rest/service/v2/admin/shell
Purpose
Creates a new shell with additional properties such as Options, Links, Currency, Images, and Gateway Integration. You can create only one new shell with each request.
Note: If auto-numbering is set, the shell number in the response might not be the same as the input.
This REST service further supports all options available through the user interface, including:
- All currencies added by the user
- Any links added by the user
- 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
- Default Calendar
- Custom Print Template
- View Forms: Form Name and Permission Structure
Request Format
Send an API request with the following structure:
{
"options":{},
"data":[]
}
Options JSON Map Format
In the "options" object, you can include the following parameters:
"options":{
"copy_from_shell_template": "<value>",
"copy_modules": "<value>",
"default_currency": "<value>" }
}
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.
uuu_shell_addl_props Key JSON Map Format
To support all other tabs, specify a uuu_shell_addl_props key with the following JSON map structure:
{
"uuu_shell_addl_props":
{
"options": { },
"links": [ ],
"currency": [ ],
"images": { },
"gateway": [ ]
}
}
All keys within uuu_shell_addl_props key are optional. The folllowing topics provide a detailed listing of all optional request parameters supported in each submap listed above within the uuu_shell_addl_props key.
Request Parameters Supported in "Options" JSON Map
The following parameters can be included in the request:
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
copy_from_shell_template | Yes | String | The name of the shell template |
copy_modules | No | String | Indicates whether the sub-modules are to be copied to the new shell. Choices include: Yes or No (default). |
default_currency | No | String | The currency code available in the Shell template/Company Currencies. If a currency code is not specified, defaults to the currency code of the shell template. |
Optional Request Parameters Supported in uuu_shell_addl_props Key
To support optional fields in the request, specify a uuu_shell_addl_props key with the following JSON map structure.
{
"uuu_shell_addl_props": {
"options": { },
"links": [ ],
"currency": [ ],
"images": { },
"gateway": [ ]
}
}
All keys within the uuu_shell_addl_props key are optional. The following topics provide a detailed listing of all optional request parameters supported in each submap listed above within the uuu_shell_addl_props key.
Optional Request Parameters Supported in the "Options" JSON Map of uuu_shell_addl_props Key
Specify optional "options" within the "uuu_shell_addl_props" key using the following JSON Map structure:
{
"uuu_shell_addl_props": {
"options": {
"dmFormUsed": "<value>",
"financialPeriod": "<value>",
"eSign": "<value>",
"projectPhase": "<value>",
"timezone": "<value>",
"notification": {
"users": []
},
}
}
}
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
dmFormUsed | No | String | Document Manager value. |
financialPeriod | No | String | Financial Period value. |
eSign | No | Integer | e-Signature value. Choices include: None (Default), DocuSign, and Adobe. |
projectPhase | No | String | Project Phase value. |
timezone | No | String | Timezone value. |
notification users [] | No | String Array | List of user names. |
Optional Request Parameters Supported in the "Links" JSON Map of uuu_shell_addl_props Key
Specify optional links within the "uuu_shell_addl_props" key using the following JSON Map structure:
{
"uuu_shell_addl_props": {
"links": [
{
"name": "<value>",
"url": "<value>",
"orderId": <value>
}
]
}
}
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
name | Yes | String | The name of the link. |
url | Yes | String | URL for the link. |
orderId | No | Integer | The number that specifies the order in which the link displays in a sequence. |
Optional Request Parameters Supported in Currency JSON list [] in uuu_shell_addl_props Key
Specify optional currency values within the "uuu_shell_addl_props" key using the following JSON Map structure:
{
"uuu_shell_addl_props": {
"currency": [
{
"currencyCode": "<value>",
"rateType": "<value>",
"rate": <value>
"comments": "<value>",
}
]
}
}
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
currencyCode | Yes | String | The currency code. |
rateType | Yes | String | Indicate the type of currency. Choices include: FLOAT (default) or PEG. |
rate | No | Number (Decimal supported) | Specify the rate only if the rate type is PEG. |
comments | No | String | Enter more details about the currency. |
Optional Request Parameters Supported in the "Images" JSON Map of uuu_shell_addl_props Key
Specify optional "Images" within the "uuu_shell_addl_props" key using the following JSON Map structure:
{
"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": <value>
}
}
}
}
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
The following parameters are supported for shell_images. | |||
file_name | Yes | String | The image file name included in the zip file. Choices include: GIF, PNG, JPG, JPEG, TIF, TIFF |
title | Yes | String | Name of the new image |
The following parameters are supported for attachments. | |||
zipped_file_content | Yes | String | Base64 content of the ZIP file |
zipped_file_name | Yes | String | Original ZIP file name |
zipped_file_size | Yes | String | Original ZIP file size in bytes |
Optional Request Parameters Supported in the "gateway" JSON Map of uuu_shell_addl_props Key
Specify optional "gateway" within the "uuu_shell_addl_props" key using the following JSON Map structure:
{
"uuu_shell_addl_props": {
"gateway": [
{
"p6_project_id": "<value>"
},
{
"p6_project_id": "<value>"
}
]
}
}
Request Parameters | Required? | Data Type | Description |
|---|---|---|---|
p6_project_id | Yes | String | The P6 EPPM project ID configured in the Primavera Gateway application. |
Response Format
The REST service returns a JSON Map in the following format:
{
"data": [],
"message": [],
"status": <REST status code value>,
"rest_audit_id": <value>
}
Response Parameters Supported in JSON Map
The following response parameters are supported in the above response format:
Request Parameters | Data Type | Description |
|---|---|---|
data | String | The name of the shell template |
message | String | Each JSON map as the response for every request. { "message": [ { "<shellNumberDE>": "", "_record_status": "", "errors": [] } ] } where:
|
status | Integer | The overall REST status code |
rest_audit_id | Integer | The audit ID |
Sample Success Request
In addition to the data, a successful response displays:
- a response "status" code of 200
- a
_record_statuskey with a "SUCCESS" value or an error message
{
"data": [
{
"uBuildingNumber": "BLDCBS - 0006",
"uuu_administrator": "Company Administrator",
"uuu_location": "/All Properties",
"uuu_shell_addl_props": {
"images": {
"shell_images": [
{
"file_name": "Image_1.png",
"title": "image one"
},
{
"file_name": "Image_2.png",
"title": "image two"
}
],
"_attachment": {
"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAASW1hZ2VfMS5wbmfrDPBz5+WS4mJgYOD19HAJYmBgnADCHGxAkYb9ZmcYGDiWero4hlTMeXt3b/bkWvljD+OX1Lc94l7UIRSt6ypy8OjRo6qRPl4rOXbt3GEZEXMnJubIyZOe0/1ira4udHYU2SViVaIhwtXa1PHI+91am9od8W8yJ2lPl2MvOVta9uvD3rYlF19/",
"zipped_file_size": 15657,
"zipped_file_name": "Image.zip"
}
},
"options": {
"dmFormUsed": "Folder and Document Attributes",
"financialPeriod": "FP1",
"eSign": "Default",
"projectPhase": "Preplanning",
"timezone": "(UTC-12:00) International Date Line West",
"notification": {
"users": ["tt"]
}
},
"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": "EVM242"
},
{
"p6_project_id": "EVM241"
}
]
},
"uBuildingName": "W_BUILDING_CBS 0006"
}
],
"message": [
{
"uBuildingNumber": "BLDCBS - 0006",
"_record_status": "SUCCESS"
}
],
"status": 200,
"rest_audit_id": 9074
}
Sample Failure Request
The following is an example of a failed request.
{
"options": {
"copy_from_shell_template": "BPCBS_T0001",
"copy_modules": "yes",
"default_currency": "AFN"
},
"data": [
{
"uBuildingNumber": "BLDCBS - 0007",
"uBuildingName": "W_BUILDING_CBS 0007",
"uuu_location": "/All Properties",
"uuu_administrator": "Company Administrator",
"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"]
}
},
"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": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAASW1hZ2VfMS5wbmfrDPBz5+WS4mJgYOD19HAJYmBgnADCHGxAkYb9ZmcYGDiWero4hlTMeXt3b/bkWvljD+OX1Lc94l7UIRSt6ypy8OjRo6qRPl4rOXbt3GEZEXMnJubIyZOe0/1ira4udHYU2SViVaIhwtXa1PHI+91am9od8W8yJ2lPl2MvOVta9uvD3rYlF19/rWJl4HsRcJWZYYU6I6OCkgKDCwtLQ0cDg4CgAIMSE5PDkjLGn9/eRs+cPVs7OTl56cWML3/",
"zipped_file_name": "Image.zip",
"zipped_file_size": 15657
}
}
}
}
]
}
Sample Failure Response
The following is an example of the response to the above sent failed request. A failed response displays a status code and error messages in the body of the "message".
{
"data": [
{
"uBuildingNumber": "BLDCBS - 0007",
"uuu_administrator": "Company Administrator",
"uuu_location": "/All Properties",
"uuu_shell_addl_props": {
"images": {
"shell_images": [
{
"file_name": "Image_1.pg",
"title": "image one"
},
{
"file_name": "Image_10.png",
"title": "image two"
}
],
"_attachment": {
"zipped_file_content": "UEsDBBQAAAAIAHhl7lZhg1mDOAQAAN4IAAALAAAASW1hZ2VfMS5wbmfrDPBz5+WS4mJgYOD19HAJYmBgnADCHGxAkYb9ZmcYGDiWero4hlTMeXt3b/bkWvljD+OX1Lc94l7UIRSt6ypy8OjRo6qRPl4rOXbt3GEZEXMnJubIyZOe0/1ira4udHYU2SViVaIhwtXa1PHI+91am9od8W8yJ2lPl2MvOVta9uvD3rYlF19/rWJl4HsRcJWZYYU6I6OCkgKDCwtLQ0cDg4CgAIMSE5PDkjLGn9/eRs+cPVs7OTl56cWML3/f//",
"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": {
"users": ["tts"]
}
},
"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"
}
]
},
"uBuildingName": "W_BUILDING_CBS 0007"
}
],
"message": [
{
"uBuildingNumber": "BLDCBS - 0007",
"_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",
"Invalid timezone",
"DM name does not exist",
"Non-image files found in the request"
]
}
],
"status": 3000,
"rest_audit_id": 9076
}
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 |
|---|---|---|---|
copy_from_shell_template | The key is missing or an incorrect shell template name is given. | 812 | Copy from shell/template number is not correct |
default_currency | An incorrect currency code is included in the request. | 3000 | Shell not created due to an invalid currency code |
In the "links" JSON map: | |||
name | The name is not specified in the request | 3000 | Name is a required field. |
name | The name is more than 50 characters in length. | 3000 | name is invalid; cannot exceed 50 chars |
In the "currency" JSON map: | |||
currencyCode | The currencyCode is not included in the request. | 3000 | currencyCode is a required field |
currencyCode | The currencyCode is invalid. | 3000 | Currency exchange rates are not available |
currencyCode | The base currency of the project is altered. | 3000 | Update to the currency is not allowed because it matches Company Currency |
currencyCode | Multiple currency details are available for the 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, but no rate is included in the request. | 3000 | Rate value for the PEG type is not a number |
comments | The length of the comments is more than 250 characters. | 3000 | Comments are invalid; cannot exceed 250 chars |
In the "options" JSON map: | |||
projectPhase | The projectPhase does not have a value in the request. | 3000 | Invalid project phase. |
projectPhase | Multiple values are found with a given value. | 3000 | Multiple Project phase found |
timezone | No timezone is found with a given value. | 3000 | Invalid timezone |
timezone | Multiple timezones are found with a given value. | 3000 | Multiple timezone entries found |
financialPeriod | No financial period is found with a given value. | 3000 | Financial period does not exist |
notification → users | An invalid user is included in the request. | 3000 | User(s) do not have access or not found: user1, user2. |
dmFormUsed | No document manager is found with a 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 |
In the "images" JSON map: | |||
file_name | An invalid request is found in the request. | 3000 | Invalid JSON structure found in the request for additional properties |
file_name | The file_name is missing. | 3000 | File_name and title are required for shell images |
file_name | Other image formats included in the request | 3000 | File upload prevented due to blocked file extension |
title | The title is missing. | 3000 | file_name and title are required for shell images |
zipped_file_content | Non-images are found in the zip file. | 3000 | Non-image files found in the request |
zipped_file_content | no image is available in the zip. | 3000 | No images found in the ZIP file |
zipped_file_content | Issue in 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 |
In the "gateway" JSON map: | |||
p6_project_id | An 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 | Trying to delete the integrated project. | 3000 | Unable to delete the project as it is integrated. |
p6_project_id | Same project available in other shells | 3000 | Same project available in the other shells: EVM > shell name |
Related Topics
Last Published Tuesday, July 1, 2025