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. The shell status defaults to Active if the shell is not created by copying from a template or the status is not specified.

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:

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:

  1. Go to the Company Workspace tab and switch to Admin mode.
  2. In the left Navigator, select uDesigner, and then select Shell Manager.
  3. Open the [shell template].
  4. 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 active 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 Acrobat Sign.

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:

  • <shellNumberDE> is the unique key for each shell
  • "_record_status" indicates the status of each shell
  • "errors" displays any errors in processing the additional properties

 

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:

{

"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

copy_from_shell_template

The specified template is marked Inactive.

827

The specified template for 'copy_from_shell_template' is inactive.

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

Shell Manager

Update Shell

Get Shell

Get Project List



Last Published Wednesday, April 9, 2025