CustomFields_Add Operation

Applies to QAComplete 12.80 SaaS, last modified on April 20, 2021

Adds a new custom field to the specified QAComplete project and area (Defects, Requirements, and so on). You can use this operation to add fields of the following types:

  • Text
  • Check Box
  • Numeric
  • Date
  • Choice List (List of All Project Users)
  • Choice List (List of All Users)
  • Phone
  • SSN

To add the Choice List (List of Values) and Choice List (Multiselect) fields, use CustomFields_AddLookUp.

To specify a project and an area to add a field to, use the AuthenticationData.ProjId and CustomField.EntityCode values in the request body.

Requirements

The web service user must belong to a user group that has the Manage custom fields privilege.

Parameters

The operation uses the following parameters:

AuthenticationData  :  AuthenticationData, required

An AuthenticationData object containing the login information and the project ID to which you want to add a custom field.

CustomField  :  CustomField, required

A CustomField object with the field data. This object must have at least the CustomFieldNbr, EntityCode, FieldName, and FieldType properties specified. For Text fields, you must also specify FieldSize – up to 8000 for fields 1..10 and up to 100 for fields 11..90.

Result

The internal ID of the added custom field.

Remarks

Text fields at numbers 11..90 are plain text fields. Text fields 1..10 can be plain text or rich text:

  • To create a rich text field, use the following field properties:

    • CustomFieldNbr – 1 .. 10

    • FieldName – A name without underscores ( _ )

    • FieldSize – 101 .. 8000 (recommended 8000)

  • To create a plain text field, use FieldName with underscores ( _ ), or FieldSize of 100 characters or less, or both.

If a custom field already exists at the specified number (CustomField.CustomFieldNbr), the operation overwrites it.

Example

Sample Code

The following example adds a check box labeled Critical Issue to defects.

C#

string login = "john.doe@example.com";
string password = "p@ssword";

ServiceSoapClient service = new ServiceSoapClient();

// Prepare AuthenticationData
LoginInfo loginInfo = service.GetLoginInfo("", login, password);
AuthenticationData authData = new AuthenticationData();
authData.AppCode = loginInfo.AppCode;
authData.UserId = loginInfo.UserId;
authData.PassCode = password;
authData.DeptId = loginInfo.DeptId;
authData.ProjId = loginInfo.ProjId;

// Prepare the CustomField object
CustomField field = new CustomField();
field.CustomFieldNbr = 1;
field.EntityCode = "Bugs";
field.FieldName = "Critical Issue";
field.FieldType = "Yes / No";
field.FieldSize = 3;
field.IsRequired = "N";

// Add the custom field
int ID = service.CustomFields_Add(authData, field);

Java

String login = "john.doe@example.com";
String password = "p@ssword";

ServiceSoap service = new Service().getServiceSoap12();

// Prepare AuthenticationData
LoginInfo loginInfo = service.getLoginInfo("", login, password);
AuthenticationData authData = new AuthenticationData();
authData.setAppCode(loginInfo.getAppCode());
authData.setUserId(loginInfo.getUserId());
authData.setPassCode(password);
authData.setDeptId(loginInfo.getDeptId());
authData.setProjId(loginInfo.getProjId());

// Prepare the CustomField object
CustomField field = new CustomField();
field.setCustomFieldNbr(1);
field.setEntityCode("Bugs");
field.setFieldName("Critical Issue");
field.setFieldType("Yes / No");
field.setFieldSize(3);
field.setIsRequired("N");

// Add the custom field
int ID = service.customFieldsAdd(authData, field);

Sample Request XML

POST /psws/psws.asmx HTTP/1.1
Host: myteam.mysite.com
Content-Type: text/xml; charset=utf-8
Content-Length: 685 {Insert an appropriate value here}
SOAPAction: "http://www.pragmaticsw.com/CustomFields_Add"
 

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CustomFields_Add xmlns="http://www.pragmaticsw.com/">
      <AuthenticationData>
        <AppCode>agSP</AppCode>
        <DeptId>8162</DeptId>
        <ProjId>11873</ProjId>
        <UserId>24661</UserId>
        <PassCode>p@ssword</PassCode>
      </AuthenticationData>
      <CustomField>
        <EntityCode>Bugs</EntityCode>
        <CustomFieldNbr>1</CustomFieldNbr>
        <FieldName>Critical Issue</FieldName>
        <FieldType>Yes / No</FieldType>
        <FieldSize>3</FieldSize>
        <IsRequired>N</IsRequired>
      </CustomField>
    </CustomFields_Add>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

POST /psws/psws.asmx HTTP/1.1
Host: myteam.mysite.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 693 {Insert an appropriate value here}
 

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <CustomFields_Add xmlns="http://www.pragmaticsw.com/">
      <AuthenticationData>
        <AppCode>agSP</AppCode>
        <DeptId>8162</DeptId>
        <ProjId>11873</ProjId>
        <UserId>24661</UserId>
        <PassCode>p@ssword</PassCode>
      </AuthenticationData>
      <CustomField>
        <EntityCode>Bugs</EntityCode>
        <CustomFieldNbr>1</CustomFieldNbr>
        <FieldName>Critical Issue</FieldName>
        <FieldType>Yes / No</FieldType>
        <FieldSize>3</FieldSize>
        <IsRequired>N</IsRequired>
      </CustomField>
    </CustomFields_Add>
  </soap12:Body>
</soap12:Envelope>

Sample Response XML

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 387 {The server returns an appropriate value here}
 

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CustomFields_AddResponse xmlns="http://www.pragmaticsw.com/">
      <CustomFields_AddResult>386</CustomFields_AddResult>
    </CustomFields_AddResponse>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 397 {The server returns an appropriate value here}
 

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <CustomFields_AddResponse xmlns="http://www.pragmaticsw.com/">
      <CustomFields_AddResult>386</CustomFields_AddResult>
    </CustomFields_AddResponse>
  </soap12:Body>
</soap12:Envelope>

See Also

CustomFields_AddLookUp
CustomFields_Delete
CustomFields_Load
Custom Field Operations
SOAP API Reference

Highlight search results