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.When a shell is created which includes values to "copy_from_shell_template" field, and users or groups, or both, are copied from the selected shell template, the entries are recorded in the Users and Group Audit Logs respectively.
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 following 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 | Time zone 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 |
| 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 time zone is found with a given value. | 3000 | Invalid timezone |
| timezone | Multiple time zones 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 |